doc/specification/draft-weltman-java-sasl-01.txt

   1
   2     Internet Draft                                           Rob Weltman
   3                                                      John Gardiner Myers
   4                                                          Prasad Yendluri
   5                                                             Christine Ho
   6                                            Netscape Communications Corp.
   7                                                         October 24, 1998
   8
   9
  10               The Java SASL Application Program Interface
  11                  <draft-weltman-java-sasl-01.txt>
  12
  13
  14 Status of this Memo
  15
  16    This document is an Internet Draft.  Internet Drafts are working
  17    documents of the Internet Engineering Task Force (IETF), its Areas,
  18    and its Working Groups.  Note that other groups may also distribute
  19    working documents as Internet Drafts.
  20
  21    Internet Drafts are draft documents valid for a maximum of six
  22    months.  Internet Drafts may be updated, replaced, or obsoleted by
  23    other documents at any time.  It is not appropriate to use Internet
  24    Drafts as reference material or to cite them other than as a
  25    "working draft" or "work in progress".
  26
  27    To learn the current status of any Internet-Draft, please check the
  28    1id-abstracts.txt listing contained in the Internet-Drafts Shadow
  29    Directories on ftp.ietf.org (US East Coast), nic.nordu.net (Europe),
  30    ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
  31
  32    Copyright (C) The Internet Society (1998). All Rights Reserved.
  33
  34    Please see the Copyright section near the end of this document for
  35    more information.
  36
  37
  38
  39 Abstract
  40
  41    This document defines a client-side java language interface for
  42    using the Simple Authentication and Security Layer (SASL) mechanisms
  43    for adding authentication support to connection-based protocols. The
  44    interface promotes sharing of SASL mechanism drivers and security
  45    layers between applications using different protocols. It
  46    complements but does not replace [1], which defines and exemplifies
  47    use of the SASL protocol in a language-independent way.
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59  Expires 4/99                                                 [Page 1]
  60 \f
  61 JAVA SASL API                                             October 1998
  62
  63
  64
  65 1 Overview of the SASL classes........................................4
  66
  67  1.1  Interfaces......................................................4
  68
  69  1.2  Classes.........................................................6
  70
  71 2 Overview of SASL API Use............................................6
  72
  73 3 The java SASL classes...............................................6
  74
  75  3.1  public interface SASLClientMechanismDriver......................6
  76
  77   3.1.1 startAuthentication..........................................6
  78
  79   3.1.2 evaluateResponse.............................................8
  80
  81   3.1.3 isComplete...................................................8
  82
  83   3.1.4 getSecurityLayer.............................................8
  84
  85   3.1.5 getMechanismName.............................................8
  86
  87  3.2  public interface SASLClientCB...................................9
  88
  89  3.3  public interface SASLNamePasswordClientCB.......................9
  90
  91   3.3.1 promptNamePassword...........................................9
  92
  93   3.3.2 getID........................................................9
  94
  95   3.3.3 getPassword..................................................9
  96
  97  3.4  public interface SASLPasswordClientCB..........................10
  98
  99   3.4.1 promptPassword..............................................10
 100
 101   3.4.2 getPassword.................................................10
 102
 103  3.5  public interface SASLInfoClientCB..............................10
 104
 105   3.5.1 promptInfo..................................................11
 106
 107  3.6  public interface SASLWarningClientCB...........................11
 108
 109   3.6.1 promptWarning...............................................11
 110
 111  3.7  public interface SASLOkayCancelClientCB........................11
 112
 113   3.7.1 promptOkayCancel............................................11
 114
 115  3.8  public interface SASLGetLanguageClientCB.......................12
 116
 117   3.8.1 getLanguage.................................................12
 118
 119  3.9  public interface SASLSecurityLayer.............................12
 120
 121   3.9.1 encode......................................................12
 122
 123   3.9.2 decode......................................................13
 124
 125  3.10 public class SASLMechanismFactory..............................13
 126
 127   3.10.1  getMechanismDriver........................................13
 128
 129   3.10.2  getMechanisms.............................................13
 130
 131  3.11 public class SASLException.....................................14
 132
 133   3.11.1  Constructors..............................................14
 134
 135 4 Security Considerations............................................14
 136
 137 5 Appendix A - Sample java LDAP program using SASL...................16
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151 Expires 4/99                                                  [Page 2]
 152 \f
 153 JAVA SASL API                                             October 1998
 154
 155 Introduction
 156
 157
 158    See [1], section 3, for an introduction to and overview of the SASL
 159    framework for authentication and negotiation of a security layer.
 160    The following presents an outline of the concepts.
 161
 162    Mechanism Drivers
 163
 164     ---------------     -------------------      -----------------
 165     | Application |-----| Protocol Driver |------| MD5           |
 166     ---------------     -------------------   |  -----------------
 167                                               |
 168                                               |  -----------------
 169                                               |--| Kerberos v5   |
 170                                               |  -----------------
 171                                               |
 172                                               |  -----------------
 173                                               |--| PKCS-11       |
 174                                               |  -----------------
 175                                               |
 176                                               |
 177                                               |
 178                                               |  - - - - - - - - -
 179                                               |--| xxxYYYxxx     |
 180                                                  - - - - - - - - -
 181
 182    An application chooses a Protocol Driver specific to the protocol it
 183    wants to use, and specifies one or more acceptable mechanisms. The
 184    Protocol Driver controls the socket, and knows the format/packaging
 185    of bytes sent down and received from the socket, but does not know
 186    how to authenticate or to encrypt/ decrypt the bytes. It uses one of
 187    the Mechanism Drivers to help it perform authentication. The
 188    Protocol Driver examines each byte string received from the server
 189    during the authentication in a protocol-specific way to determine if
 190    the authentication process has been completed. If not, the byte
 191    string is passed to the Mechanism Driver to be interpreted as a
 192    server challenge; the Mechanism Driver returns an appropriate
 193    response, which the Protocol Driver can encode in a protocol-
 194    specific way and return to the server.
 195
 196    If the Protocol Driver concludes from the byte string received from
 197    the server that authentication is complete, it may query the
 198    Mechanism Driver if it considers the authentication process
 199    complete, in order to thwart early completion messages inserted by
 200    an intruder.
 201
 202    On completed authentication, the Protocol Driver receives from the
 203    Mechanism Driver a Security Layer Driver object. From this point on,
 204    the Protocol Driver passes byte arrays received from its socket to
 205    the Security Layer Driver object for decoding before returning them
 206    to the application, and passes application byte arrays to the
 207    Security Layer Driver object for encryption before passing them down
 208    the socket.
 209
 210
 211 Expires 4/99                                                  [Page 3]
 212 \f
 213 JAVA SASL API                                             October 1998
 214
 215
 216    A complication here is that some authentication methods may require
 217    additional user/application input.  That means that a Mechanism
 218    Driver may need to call up to an application during the
 219    authentication process.
 220
 221    In the following, a number of callback interfaces have been defined,
 222    allowing an application to (if necessary) provide a user with
 223    prompts and obtain additional information required to continue the
 224    process.
 225
 226    Additional callback interfaces may be defined in the future.
 227    Typically, a client will construct an object that implements all of
 228    these interfaces.
 229
 230    Protocol Drivers are protocol-dependent, and may be built in to a
 231    protocol package or an application. However, there should be a
 232    generalized framework for registering and finding Mechanism Drivers.
 233    This can be handled in a way similar to content and protocol
 234    handlers in java: look for them in a predefined place in the general
 235    class hierarchy, e.g. javax.security.mechanisms. So if a Protocol
 236    Driver is asked to use "GSSAPI", it would attempt to instantiate
 237    javax.security.mechanisms.gssapi.class. A non-standard place can
 238    also be specified, e.g. "myclasses.mechanisms.GSSAPI".  This
 239    functionality is provided by a mechanism driver factory, which knows
 240    where to find candidate classes for instantiation.
 241
 242    The Mechanism Drivers are protocol-independent, and don't deal
 243    directly with network connections, just byte arrays, so they can be
 244    implemented in a generalizable way for all protocols.
 245
 246    A Security Layer Driver typically inherits a State object from the
 247    Mechanism Driver, where parameters and resolutions reached during
 248    authentication have been stored.
 249
 250    Different Mechanism Drivers may require different parameters to
 251    carry out the authentication process. This is handled in the
 252    following with a java.util.Properties object.
 253
 254
 255 1     Overview of the SASL classes
 256
 257
 258 1.1   Interfaces
 259
 260
 261    SASLClientMechanismDriver   Interface for all SASL Mechanism
 262                                Drivers.
 263
 264
 265    SASLSecurityLayer           An object implementing this interface
 266                                 translates buffers back and forth
 267                                during a session, after the
 268
 269
 270
 271 Expires 4/99                                                  [Page 4]
 272 \f
 273 JAVA SASL API                                             October 1998
 274
 275                                authentication process has completed, to
 276                                provide a security layer.
 277
 278
 279
 280    SASLClientCB                Base interface for classes which can be
 281                                used by a Mechanism Driver to obtain
 282                                additional client information during
 283                                negotiation of authentication with a
 284                                server.
 285
 286
 287    SASLNamePasswordClientCB    An interface to provide a Mechanism
 288                                Driver with a user name and during
 289                                negotiation of authentication with a
 290                                server.
 291
 292
 293    SASLPasswordClientCB        An interface to provide a Mechanism
 294                                Driver with a password or other single
 295                                textual credential item during
 296                                negotiation of authentication with a
 297                                server.
 298
 299
 300    SASLInfoClientCB            An interface that can be used by a
 301                                Mechanism Driver to present the user
 302                                with arbitrary textual information
 303                                during negotiation of authentication
 304                                with a server.
 305
 306
 307    SASLWarningClientCB         An interface that can be used by a
 308                                Mechanism Driver to present the user
 309                                with arbitrary textual information
 310                                during negotiation of authentication
 311                                with a server, and wait for user
 312                                confirmation.
 313
 314
 315    SASLOkayCancelClientCB      An interface that can be used by a
 316                                Mechanism Driver to present the user
 317                                with a choice of continuing or
 318                                cancelling during negotiation of
 319                                authentication with a server.
 320
 321
 322    SASLGetLanguageCB           An interface that can be used by a
 323                                Mechanism Driver to query for a language
 324                                to use in localization of client-visible
 325                                text.
 326
 327
 328
 329
 330
 331 Expires 4/99                                                  [Page 5]
 332 \f
 333 JAVA SASL API                                             October 1998
 334
 335
 336 1.2   Classes
 337
 338
 339    SASLMechanismFactory            A class capable of instantiating a
 340                                    Mechanism Driver.
 341
 342
 343    SASLException                   Exception thrown on errors and
 344                                    failures in the authentication
 345                                    process.
 346
 347
 348 2     Overview of SASL API Use
 349
 350    An application generally uses the SASL API as follows:
 351
 352    -    Pass a list of acceptable or known Mechanism Drivers to a
 353         SASLMechanismFactory.  The factory returns an object
 354         implementing SASLClientMechanismDriver on success.
 355
 356    -    Create an object implementing the client authentication
 357         callback interfaces, which can provide credentials when
 358         required by the Mechanism Driver.
 359
 360    -    Have the SASLClientMechanismDriver object begin the
 361         authentication process by providing an initial server request.
 362
 363    -    Requests/responses are exchanged with the server. If a response
 364         indicates authentication has completed, the Mechanism Driver is
 365         queried for validation, and a SASLSecurityLayer object is
 366         obtained from it. If not, the Mechanism Driver is queried for
 367         an appropriate next request to the server. This continues until
 368         authentication has completed.
 369
 370    -    For the rest of the session, requests to the server are encoded
 371         first by the Security Layer, and responses from the server are
 372         decoded by it before processing in the application.
 373
 374    The following sections describe the SASL classes in more detail.
 375
 376
 377 3     The java SASL classes
 378
 379
 380 3.1   public interface SASLClientMechanismDriver
 381
 382    An object implementing this interface can negotiate authentication
 383    using one or more authentication methods.
 384
 385
 386 3.1.1 startAuthentication
 387
 388    public byte[]
 389
 390
 391 Expires 4/99                                                  [Page 6]
 392 \f
 393 JAVA SASL API                                             October 1998
 394
 395    startAuthentication(String id,
 396                        String protocol,
 397                        String serverName,
 398                        java.util.Properties props,
 399                        SASLClientCB authCB)
 400                        throws SASLException
 401
 402    This method prepares a byte array to use for the initial request to
 403    authenticate. A SASLException is thrown if the driver cannot
 404    initiate authentication with the supplied parameters.  The return
 405    value may be null, indicating there is no initial response to send
 406    to the server.
 407
 408    Parameters are:
 409
 410       id             Protocol-dependent identification, e.g. user name
 411                       or distinguished name.
 412
 413       protocol       A protocol supported by the mechanism driver, e.g
 414                       "POP", "LDAP".
 415
 416       serverName     Fully qualified name of server to authenticate
 417                       to.
 418
 419       props          Additional configuration for the session, e.g.
 420
 421            security.policy.encryption.minimum      Minimum key length;
 422                                                     default 0 (no
 423                                                     session
 424                                                     protection). 1
 425                                                     means integrity
 426                                                     protection only.
 427
 428            security.policy.encryption.maximum      Maximum key length;
 429                                                     default 256.
 430
 431            security.policy.server_
 432                                   authentication   True if server must
 433                                                     authenticate to
 434                                                     client; default
 435                                                     false.
 436
 437            security.ip.local                       For kerberos v4; no
 438                                                     default.
 439
 440                                                    security.ip.remote
 441                                                     For kerberos v4; no
 442                                                     default.
 443
 444            security.maxbuffer                      Maximum size of
 445                                                     security layer
 446                                                     frames; default 0
 447                                                     (client will
 448                                                     not use the
 449                                                     security layer).
 450
 451
 452 Expires 4/99                                                  [Page 7]
 453 \f
 454 JAVA SASL API                                             October 1998
 455
 456
 457       authCB         An optional object which can be invoked by the
 458                       mechanism driver to acquire additional
 459                       authentication information, such as user name and
 460                       password.
 461
 462
 463 3.1.2 evaluateResponse
 464
 465    public byte[]
 466    evaluateResponse(byte[] challenge)
 467                     throws SASLException
 468
 469    If a challenge is received from the server during the authentication
 470    process, this method is called by the Protocol Driver to prepare an
 471    appropriate next request to submit to the server. A SASLException is
 472    thrown if no response can be generated for the challenge.
 473
 474    Parameters are:
 475
 476       challenge      Received server challenge.
 477
 478
 479 3.1.3 isComplete
 480
 481    public boolean
 482    isComplete()
 483
 484    This method may be called at any time to determine if the
 485    authentication process is finished. Typically, the protocol driver
 486    will not do this until it has received something from the server
 487    which indicates (in a protocol-specific manner) that the process has
 488    completed.
 489
 490 3.1.4 getSecurityLayer
 491
 492    public SASLSecurityLayer
 493    getSecurityLayer() throws SASLException
 494
 495    Once authentication is complete, the Protocol Driver calls this
 496    method to obtain an object capable of encoding/decoding data content
 497    for the rest of the session (or until there is a new round of
 498    authentication). An exception is thrown if authentication is not yet
 499    complete.
 500
 501
 502 3.1.5 getMechanismName
 503
 504    public String
 505    getMechanismName()
 506
 507    Report the name of this driver, e.g. "GSSAPI".
 508
 509
 510
 511
 512 Expires 4/99                                                  [Page 8]
 513 \f
 514 JAVA SASL API                                             October 1998
 515
 516 3.2   public interface SASLClientCB
 517
 518    Base interface for objects which can be called by a Mechanism
 519    Driver to provide more information for authentication.
 520
 521
 522 3.3   public interface SASLNamePasswordClientCB
 523    extends SASLClientCB
 524
 525    An object implementing this interface can be called by a Mechanism
 526    Driver to provide more information for authentication.  Typically
 527    what is provided by the object is an ID and a password.
 528
 529
 530 3.3.1 promptNamePassword
 531
 532    public boolean
 533    promptNamePassword (String defaultID,
 534                        String serverFQDN,
 535                        String protocol,
 536                        String prompt)
 537
 538    Method to be implemented by client of the mechanism driver. It may
 539    or may not pop up a UI and allow a user to enter the information. It
 540    returns true unless the operation was cancelled.
 541
 542    Parameters are:
 543
 544       defaultID      A default which may be used in selecting
 545                       credentials.
 546
 547       serverFQDN     The fully qualified domain name of the host to
 548                       which authentication is being attempted. Used
 549                       with kerberos.
 550
 551       protocol       "IMAP", "POP", etc. Used with kerberos.
 552
 553       prompt         Textual information to be provided to the client
 554                       for obtaining an ID and password. It may be
 555                       localized.
 556
 557
 558 3.3.2 getID
 559
 560    public String
 561    getID ()
 562
 563    Called by a mechanism driver to retrieve the ID (e.g. user name)
 564    obtained by the object during promptNamePassword.
 565
 566
 567 3.3.3 getPassword
 568
 569    public String
 570
 571
 572 Expires 4/99                                                  [Page 9]
 573 \f
 574 JAVA SASL API                                             October 1998
 575
 576    getPassword ()
 577
 578    Called by a mechanism driver to retrieve the password obtained by
 579    the object during promptNamePassword.
 580
 581
 582 3.4   public interface SASLPasswordClientCB
 583    extends SASLClientCB
 584
 585    An object implementing this interface can be called by a Mechanism
 586    Driver to provide more information for authentication.  Typically
 587    what is provided by the object is a password.
 588
 589
 590 3.4.1 promptPassword
 591
 592    public boolean
 593    promptPassword (String defaultID,
 594                    String serverFQDN,
 595                    String protocol,
 596                    String prompt)
 597
 598    Method to be implemented by client of the mechanism driver. It may
 599    or may not pop up a UI and allow a user to enter the information. It
 600    returns true unless the operation was cancelled.
 601
 602    Parameters are:
 603
 604       defaultID      A default which may be used in selecting
 605                       credentials.
 606
 607       serverFQDN     The fully qualified domain name of the host to
 608                       which authentication is being attempted. Used
 609                       with kerberos.
 610
 611       protocol       "IMAP", "POP", etc. Used with kerberos.
 612
 613       prompt         Textual information to be provided to the client
 614                       for obtaining a password. It may be localized.
 615
 616
 617 3.4.2 getPassword
 618
 619    public String
 620    getPassword ()
 621
 622    Called by a mechanism driver to retrieve the password obtained by
 623    the object during promptPassword.
 624
 625
 626 3.5   public interface SASLInfoClientCB
 627    extends SASLClientCB
 628
 629    An object implementing this interface can be called by a Mechanism
 630
 631
 632 Expires 4/99                                                 [Page 10]
 633 \f
 634 JAVA SASL API                                             October 1998
 635
 636    Driver to present information to a user. No confirmation is
 637    expected.
 638
 639 3.5.1 promptInfo
 640
 641
 642    public void
 643    promptInfo (String prompt)
 644
 645    Method to be implemented by client of the mechanism driver. It
 646    presents the user with the supplied textual information.
 647
 648    Parameters are:
 649
 650       prompt         Textual information to be provided to the client.
 651                       It may be localized.
 652
 653
 654 3.6   public interface SASLWarningClientCB
 655    extends SASLClientCB
 656
 657    An object implementing this interface can be called by a Mechanism
 658    Driver to present information to a user.  The user must take some
 659    action to proceed.
 660
 661
 662 3.6.1 promptWarning
 663
 664
 665    public void
 666    promptWarning (String prompt)
 667
 668    Method to be implemented by client of the mechanism driver. It
 669    presents the user with the supplied textual information and waits
 670    for the user to take some action to proceed.
 671
 672    Parameters are:
 673
 674       prompt         Textual information to be provided to the client.
 675                       It may be localized.
 676
 677
 678 3.7   public interface SASLOkayCancelClientCB
 679    extends SASLClientCB
 680
 681    An object implementing this interface can be called by a Mechanism
 682    Driver to present information to a user and return an indication
 683    that an operation is to proceed or to be cancelled.
 684
 685
 686 3.7.1 promptOkayCancel
 687
 688
 689    public boolean
 690
 691
 692 Expires 4/99                                                 [Page 11]
 693 \f
 694 JAVA SASL API                                             October 1998
 695
 696    promptOkayCancel (String prompt,
 697                      String okText,
 698                      String cancelText )
 699
 700    Method to be implemented by client of the mechanism driver. It
 701    presents the user with the supplied textual information. The return
 702    value is true to continue operations, false to abort. This may be
 703    implemented with OK and CANCEL buttons in a dialog. If okText and/or
 704    cancelText are non-null and not empty, they may be used to label
 705    buttons.
 706
 707    Parameters are:
 708
 709    prompt       Textual information to be provided to the client. It
 710    may be localized.
 711
 712    okText       Optional label for OK button or selection.
 713
 714    cancelText   Optional label for Cancel button or selection.
 715
 716
 717 3.8   public interface SASLGetLanguageClientCB
 718    extends SASLClientCB
 719
 720    An object implementing this interface can be called by a Mechanism
 721    Driver to obtain a language to use for localization of user-visible
 722    text.
 723
 724
 725 3.8.1 getLanguage
 726
 727    public String
 728    getLanguage ()
 729
 730    Method to be implemented by client of the mechanism driver. It
 731    returns a language to use in localizing user-visible text.
 732
 733
 734 3.9   public interface SASLSecurityLayer
 735
 736    An object implementing this interface translates buffers back and
 737    forth during a session, after the authentication process has
 738    completed, to provide a security layer.
 739
 740
 741 3.9.1 encode
 742
 743    public byte[]
 744    encode(byte[] outVals) throws SASLException
 745
 746    Take a protocol-dependent byte array and encode it (encrypt, for
 747    example) for sending to the server.
 748
 749
 750
 751
 752 Expires 4/99                                                 [Page 12]
 753 \f
 754 JAVA SASL API                                             October 1998
 755
 756 3.9.2 decode
 757
 758    public byte[]
 759    decode(byte[] inVals) throws SASLException
 760
 761    Take an encoded byte array received from the server and decode it.
 762
 763    Parameters are:
 764
 765       outVals        A request to be encoded before sending to the
 766                       server.
 767
 768       inVals         A response received from the server, to be
 769                       decoded.
 770
 771
 772 3.10  public class SASLMechanismFactory
 773
 774    This class can provide a SASLClientMechanismDriver, or a list of
 775    mechanisms.
 776
 777
 778 3.10.1  getMechanismDriver
 779
 780    public static SASLClientMechanismDriver
 781    getMechanismDriver(String mechanism,
 782                       String packageName)
 783                       throws SASLException
 784
 785
 786    public static SASLClientMechanismDriver
 787    getMechanismDriver(String[] mechanisms,
 788                       String packageName)
 789                       throws SASLException
 790
 791    Returns an object implementing a requested Mechanism Driver. A
 792    SASLException is thrown if no corresponding Mechanism Driver can be
 793    instantiated.
 794
 795    Parameters are:
 796
 797       mechanism      A single mechanism name, e.g. "GSSAPI".
 798
 799       mechanisms     A list of acceptable mechanisms. The first one
 800                       for which a Mechanism Driver can be instantiated
 801                       is returned.
 802
 803       packageName    A package from which to instantiate the Mechanism
 804                       Driver, e.g.  "myclasses.SASL.mechanisms". If
 805                       null, a system default is used.
 806
 807 3.10.2  getMechanisms
 808
 809    public static String[]
 810
 811
 812 Expires 4/99                                                 [Page 13]
 813 \f
 814 JAVA SASL API                                             October 1998
 815
 816    getMechanisms()
 817
 818
 819    public static String[]
 820    getMechanisms(String packageName)
 821
 822    Returns a list of available mechanisms.
 823
 824    Parameters are:
 825
 826       packageName    A package from which to instantiate the Mechanism
 827                       Driver, e.g.  "myclasses.SASL.mechanisms". If
 828                       null, a system default is used.
 829
 830
 831 3.11  public class SASLException
 832    extends Exception
 833
 834    Exception thrown on errors and failures in authentication.
 835
 836
 837 3.11.1  Constructors
 838
 839    public SASLException()
 840
 841    Constructs a default exception with no specific error information.
 842
 843
 844    public SASLException(String message, int resultCode)
 845
 846
 847    Constructs a default exception with a specified string as additional
 848    information, and a result code.
 849
 850
 851    Parameters are:
 852
 853       message        Additional error information.
 854
 855       resultCode     The result code to return.
 856
 857
 858
 859 4     Security Considerations
 860
 861    When SASL authentication is performed over unsecured connections, it
 862    is possible for an active attacker to spoof the server's protocol-
 863    specific indication that authentication is complete.  Clients should
 864    protect against this attack by verifying the completion of
 865    authentication with the mechanism driver by calling the driver's
 866    isComplete() method.
 867
 868    Additional security considerations are discussed in [1].
 869
 870
 871
 872 Expires 4/99                                                 [Page 14]
 873 \f
 874 JAVA SASL API                                             October 1998
 875
 876
 877    Bibliography
 878
 879    [1]  J. Myers, "Simple Authentication and Security Layer (SASL)",
 880    Internet Draft draft-myers-auth-sasl-12.txt, September 1997
 881
 882
 883    Authors' Addresses
 884
 885       Rob Weltman
 886       Netscape Communications Corp.
 887       501 E. Middlefield Rd.
 888       Mail Stop MV-029
 889       Mountain View, CA 94043-4042
 890       USA
 891       Email: rweltman@netscape.com
 892
 893       John Gardiner Myers
 894       Netscape Communications Corp.
 895       501 E. Middlefield Rd.
 896       Mail Stop MV-029
 897       Mountain View, CA 94043-4042
 898       USA
 899       Email: jgmyers@netscape.com
 900
 901       Prasad Yandluri
 902       Netscape Communications Corp.
 903       501 E. Middlefield Rd.
 904       Mail Stop MV-029
 905       Mountain View, CA 94043-4042
 906       USA
 907       Email: prasad@netscape.com
 908
 909       Christine Ho
 910       Netscape Communications Corp.
 911       501 E. Middlefield Rd.
 912       Mail Stop MV-029
 913       Mountain View, CA 94043-4042
 914       USA
 915       Email: chrisho@netscape.com
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932 Expires 4/99                                                 [Page 15]
 933 \f
 934 JAVA SASL API                                             October 1998
 935
 936 5     Appendix A - Sample java LDAP program using SASL
 937
 938    /****************************************************************
 939     It might look like this in LDAP. The Protocol Driver is
 940     implemented as part of the authenticate method of
 941     LDAPConnection.
 942    ****************************************************************/
 943
 944    public class LDAPConnection {
 945      public void authenticate( String dn,
 946                                String mechanism,
 947                                String packageName,
 948                                Properties props,
 949                                SASLClientCB getter )
 950                                throws LDAPException {
 951        SASLClientMechanismDriver driver;
 952        try {
 953          // Get a mechanism driver
 954          driver =
 955              SASLMechanismFactory.getMechanismDriver( mechanism,
 956                                                       packageName );
 957          // Get the initial request to start authentication
 958          byte[] outVals = driver.startAuthentication( dn,
 959                                                       "LDAP",
 960                                                       getHost(),
 961                                                       props,
 962                                                       getter );
 963          getSocketOutput().writeRequest( outVals );
 964          // Get the server response
 965          byte[] inVals = getSocketInput().readResponse();
 966          // Authentication done?
 967          while ( !checkForCompletion( inVals ) ) {
 968            // No, get an appropriate next request and send it off
 969            outVals = driver.evaluateResponse( inVals );
 970            getSocketOutput().writeRequest( outVals );
 971            inVals = getSocketInput().readResponse();
 972          }
 973          // Make sure authentication REALLY is complete
 974          if ( !driver.isComplete() ) {
 975            /* Authentication session hijacked! */
 976            throw new LDAPException();
 977          }
 978          security = driver.getSecurityLayer();
 979        } catch ( SASLException e ) {
 980          throw new LDAPException();
 981        } catch ( IOException e ) {
 982          throw new LDAPException();
 983        }
 984      }
 985
 986      private SASLSecurityLayer security = null;
 987    }
 988
 989
 990
 991
 992 Expires 4/99                                                 [Page 16]
 993 \f
 994 JAVA SASL API                                             October 1998
 995
 996    /****************************************************************
 997     This might be in an application
 998    ****************************************************************/
 999
1000    // Object to supply credentials when needed
1001    class RequestedInfoGetter implements SASLNamePasswordClientCB,
1002                                         SASLPasswordClientCB,
1003                                         SASLInfoClientCB,
1004                                         SASLWarningClientCB,
1005                                         SASLGetLanguageClientCB,
1006                                         SASLOkayCancelClientCB {
1007      public RequestedInfoGetter() {}
1008
1009      public boolean promptNamePassword ( String defaultID,
1010                                          String serverFQDN,
1011                                          String protocol,
1012                                          String prompt ) {
1013        // Put up a dialog box, get user's selected ID and password
1014        UserIDDialog dlg = new UserIDDialog();
1015        if ( dlg.doDialog( defaultID, prompt ) == OK ) {
1016         _id = dlg.getID();
1017         _password = dlg.getPassword();
1018          return true;
1019        }
1020        return false;
1021      }
1022
1023      public boolean promptPassword ( String defaultID,
1024                                      String serverFQDN,
1025                                      String protocol,
1026                                      String prompt ) {
1027        // Put up a dialog box, get user's selected password
1028        PasswordDialog dlg = new PasswordDialog();
1029        if ( dlg.doDialog( defaultID, prompt ) == OK ) {
1030         _password = dlg.getPassword();
1031          return true;
1032        }
1033        return false;
1034      }
1035
1036      public void promptWarning ( String prompt ) {
1037        // Put up a dialog box, wait for confirmation
1038        WarningDialog dlg = new WarningDialog();
1039        dlg.doDialog( prompt );
1040      }
1041      public void promptInfo ( String prompt ) {
1042        // Put the text in the status box
1043        statusWin.addText( prompt );
1044      }
1045      public boolean promptOkayCancel ( String prompt,
1046                                        String ok, String cancel ) {
1047        // Put up a dialog box, wait for OK or Cancel
1048        OkayCancelDialog dlg = new OkayCancelDialog();
1049        return dlg.doDialog( prompt );
1050
1051
1052 Expires 4/99                                                 [Page 17]
1053 \f
1054 JAVA SASL API                                             October 1998
1055
1056      }
1057
1058      public String getLanguage () {
1059        // Get the language from the locale
1060        String lang = locale.getLanguage();
1061        if ( (locale.getCountry() != null) &&
1062             (locale.getCountry().length() > 0) ) {
1063          lang += "-" + locale.getCountry();
1064          if ( (locale.getVariant() != null) &&
1065               (locale.getVariant().length() > 0) ) {
1066            lang += "-" + locale.getVariant();
1067          }
1068        }
1069        return lang;
1070      }
1071
1072      public String getID() { return _id; }
1073      public String getPassword() { return _password; }
1074
1075      private String _id;
1076      private String _password;
1077    }
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112 Expires 4/99                                                 [Page 18]
1113 \f
1114 JAVA SASL API                                             October 1998
1115
1116    /***************************************************************
1117      And so the application code to do authentication
1118    ***************************************************************/
1119
1120     // Set up all SASL parameters; some may have reasonable defaults
1121     Properties props = new Properties();
1122     props.add( "security.policy.encryption.minimum", "40");
1123     props.add( "security.policy.encryption.maximum", "128");
1124     props.add( "security.policy.server_authentication", "true");
1125     props.add( "security.maxbuffer", "4096");
1126     // The following two for kerberos v4, only
1127     //props.add( "security.ip.local", "192.68.1.10");
1128     //props.add( "security.ip.remote", "192.68.1.50");
1129
1130     // What we want to authenticate as
1131     String dn = "cn=Directory Manager";
1132
1133     // Create an object for possible use by the authentication
1134     // process
1135     RequestedInfoGetter getter = new RequestedInfoGetter();
1136
1137     try {
1138       // Note: getter methods may be called during authentication
1139       // Note: "connection" includes the SASL Protocol Driver
1140       // functionality, and it will internally manage a Mechanism
1141       // Driver for GSSAPI, and then a Security Layer object for
1142       // data translation
1143       connection.authenticate( dn, "GSSAPI", props, getter );
1144     } catch ( LDAPException e ) {
1145       // Abort, return, maybe try some other authentication
1146     }
1147
1148     // Okay. From here on, everything goes through security, but the
1149     // methods have the same signatures as if we were not using SASL
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172 Expires 4/99                                                 [Page 19]
1173 \f