idnits 2.17.1 draft-newman-sasl-c-api-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 35 longer pages, the longest (page 2) being 60 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 36 pages -- Found 36 instances of the string 'FORMFEED[Page...' -- is this a case of missing nroff postprocessing? Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 60 instances of too long lines in the document, the longest one being 42 characters in excess of 72. ** The abstract seems to contain references ([SASL]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (April 2004) is 7316 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC2026' is mentioned on line 15, but not defined -- Looks like a reference, but probably isn't: '1' on line 282 == Missing Reference: 'LDAP-API' is mentioned on line 1388, but not defined == Unused Reference: 'LDAP' is defined on line 1541, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2222 (ref. 'SASL') (Obsoleted by RFC 4422, RFC 4752) ** Obsolete normative reference: RFC 2373 (Obsoleted by RFC 3513) ** Obsolete normative reference: RFC 3066 (ref. 'LANGTAGS') (Obsoleted by RFC 4646, RFC 4647) -- Obsolete informational reference (is this intentional?): RFC 3501 (ref. 'IMAP4') (Obsoleted by RFC 9051) -- Obsolete informational reference (is this intentional?): RFC 1734 (ref. 'POP-AUTH') (Obsoleted by RFC 5034) Summary: 9 errors (**), 0 flaws (~~), 8 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Newman 3 Internet Draft: SASL C API Sun Microsystems 4 Document: draft-newman-sasl-c-api-03.txt A. Melnikov 5 Isode Ltd. 6 April 2004 7 Expires in six months 9 Simple Authentication and Security Layer C API 11 Status of this memo 13 This document is an Internet-Draft and is in full conformance with 14 all provisions of Section 10 of RFC2026 [RFC2026]. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that other 18 groups may also distribute working documents as Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 0. Meta-information on this draft 33 This information is intended to facilitate discussion. It will be 34 removed when this document leaves the Internet-Draft stage. 36 Editorial comments are marked with << and >>. 38 0.1. Changes since 02 40 1. Replaced sasl_version() with sasl_version_info(). 42 2. Added missing reference for GSSAPI. 44 3. Moved some functions between different sections. 46 4. Added description of sasl_encodev, sasl_utf8verify. 48 0.1. Changes since 01 50 1. Clarified the purpose of sasl_errdetail. 52 2. Clarified what happens when sasl_client_start called second time. 54 3. Clarified the meaning of sasl_getsecret_t returning SASL_OK with 55 psecret set to NULL. 57 4. Added more text clarifying callback/interactions relationship. 59 5. Fixed the description of SASL flags to sasl_client_start/ 60 sasl_server_start. 62 6. Clarified IP address syntax and added proper references. 64 7. Replaced references to RFC 1766 with RFC 3066. 66 8. Clarified how an application can control the order of SASL 67 mechanism selection on the client side. 69 9. Clarified relationship between serverFQDN and user_realm in 70 sasl_server_new. 72 10. Split References to Normative and Informative. 74 11. Added sasl_version function description. 76 12. Clarified usage of callbacks parameter in sasl_client_init/ 77 sasl_server_init. 79 13. Clarified that appname parameter to sasl_server_init must be NULL 80 for a library. Added a new property for setting/querying this 81 value. 83 14. Clarified that sasl_done must be called for each call to 84 sasl_server_init/sasl_client_init and that reference counters 85 should be used internally by SASL C API implementations. 87 15. Clarified which strings are NUL terminated. This is an ongoing 88 effort. 90 16. Updated description of different properties, the list should be 91 complete now. 93 17. Clarified how sasl_server_init should derive user_realm/ 94 serverFQDN if one is not provided. 96 18. Added a draft version of text that explains how sasl_encode 97 should be called properly. 99 19. Clarified that sasl_decode must concatenate data if multiple SASL 100 encoded blocks are provided in the same input buffer. 102 20. Added an additional error code to sasl_getprop/sasl_setprop. 104 0.2. ToDo 106 The list of major pending changes/additions is listed below: 108 1. Add sasl_authorize and sasl_log callbacks. 110 2. Add a new function for server interactions. 112 3. Enabling SASL EXTERNAL mechanism on the client side. 114 4. A lot of cleanup work: for each parameter define what to do if it 115 is NULL, empty string, negative, etc. Clarify thread safety 116 issues. Clarify when different fields allocated by the library 117 are called. 119 5. Add sasl_user_exists and sasl_setpass? 121 Abstract 123 Almost every protocol needs authentication. However, there does not 124 exist an authentication mechanism suitable for all organizations, nor 125 is it likely that a small fixed set of authentication mechanisms will 126 remain suitable. SASL [SASL] provides the on-the-wire framework for 127 authentication (and a security layer) which separates the design of 128 authentication mechanisms from the protocols in which they're used. 130 The SASL protocol model suggests a software architecture where 131 application protocols call a generic API to authenticate which in 132 turn calls a generic plug-in interface for extensible authentication 133 modules. This memo documents the API used in one implementation of 134 this architecture in the hope that it will be useful to others. An 135 associated memo documenting the plug-in interface is forthcoming. 137 1. Conventions Used in this Memo 139 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" 140 in this document are to be interpreted as defined in "Key words for 141 use in RFCs to Indicate Requirement Levels" [KEYWORDS]. 143 This assumes familiarity the SASL [SASL] specification. 145 When describing function parameters the following conventions are 146 used: IN before the parameter means that the function expects this 147 paramer to be specified; OUT means that the function sets the 148 parameter upon return; INOUT means that the function requires the 149 parameter to be specified and will update its value upon return. 151 1.1. Concepts 153 The following concepts are necessary to understand this 154 specification. 156 realm 157 A realm is a name (usually a domain-style name) associated with a 158 set of users on a server. One realm may span multiple servers. 159 Alternatively, a single server may have multiple realms. Thus 160 there may be multiple users with the username "chris" on the same 161 server, each in a different realm. Some authentication mechanisms 162 have a special field for the realm (e.g., DIGEST-MD5). For other 163 mechanisms, a realm can be specified by the client by using the 164 syntax "username@realm" in the username field. 166 service 167 A service is a basic function provided by one or more protocols. 168 The GSSAPI service name [GSSAPI] registry is available at: 170 172 This registry is used by SASL and the SASL API. The service name 173 may be used for service-specific passwords for advanced users, or 174 advanced authentication mechanisms may restrict the services a 175 given server may offer. 177 virtual domain 178 When a single server has multiple realms and there is a DNS server 179 entry for each realm pointing to the same server IP address, then 180 those realms are "virtual domains". Virtual domains are extremely 181 popular with web hosting services and are becoming more popular 182 with POP mail services. The key to providing virtual domain sup- 183 port is that the client informs the server of the domain it 184 believes it is speaking to either through a special protocol ele- 185 ment or by using a username of the form "user@realm". 187 2. Overview of the SASL C API 189 The SASL API is initialized once at process startup. The 190 sasl_server_init() and sasl_client_init() functions provide basic 191 initialization. 193 When a network connection occurs where SASL will be used, a connec- 194 tion-specific context is created for authentication with 195 sasl_client_new() or sasl_server_new(). The API implementation must 196 support multi-threaded servers and clients by creating the connection 197 context in a thread-safe fashion permitting multiple contexts in a 198 given process. At this point, the caller may adjust security policy 199 for the context, and the set of mechanisms which are enabled is 200 determined by requirements from the configuration or by the caller. 202 The server end of the API may request a list of enabled authentica- 203 tion mechanisms either in general or for a specific user. The client 204 may either select a single mechanism or request a list from the 205 server (if the SASL profile for the protocol in question supports 206 that) and pass the list to the API for automated mechanism selection 207 by configured policy. 209 The SASL exchange begins with sasl_client_start() which determines if 210 one of the desired mechanisms is available on the client and may gen- 211 erate an initial client response. The client then sends the appro- 212 priate protocol message to initiate the SASL exchange that the server 213 passes to sasl_server_start(). 215 The SASL exchange continues with calls to sasl_client_step() and 216 sasl_server_step(), until the server indicates completion or the 217 client cancels the exchange. 219 The server queries the user name and user realm resulting from the 220 exchange with the sasl_getprop() routine. 222 A connection context is released with sasl_dispose() and process ter- 223 mination is indicated with sasl_done(). 225 There are a number of utility functions and customization functions 226 available in the API for additional services. 228 Note, that all functions described in this document can be imple- 229 mented as macroses, so an application using this API MUST NOT assume 230 that they are functions. 232 An application or library trying to use the SASL API described in 233 this document must include "sasl.h" include file. 235 3. Basic SASL API Routines 237 This section describes the types and functions likely to be used by 238 every caller of the SASL API. 240 3.1. Basic SASL API Data Structures 242 The following datastructures are basic to the SASL API. 244 3.1.1. sasl_callback_t 246 The sasl_callback_t structure is used for the caller of the SASL API 247 to provide services to both the core SASL API and SASL mechanisms via 248 callbacks. The most important callback is the "getopt" callback (see 249 section 3.2.3) which is used to retrieve security policy option set- 250 tings from the caller's preferences. 252 typedef struct sasl_callback { 253 unsigned int id; 254 int (*proc)(); 255 void *context; 256 } sasl_callback_t; 258 id is the label for the callback (XXX IANA registry needed), proc is 259 a function pointer whose exact type is determined by the id, and con- 260 text is a context variable which will be passed to the callback (usu- 261 ally as the first argument). The last callback in the list of call- 262 backs is indicated with an id of SASL_CB_LIST_END. 264 If proc is NULL, this means that the application doesn't want to 265 specify a corresponding callback, but would provide the necessary 266 data via interaction. See also section 3.1.4. 268 A SASL mechanism has a list of required callbacks. If all the 269 required callbacks are not provided by the calling application (or 270 not handled as interactions), the SASL mechanism is not going to be 271 selected. Thus it is necessary to list all callbacks that are pro- 272 vided by the application and list all interactions as callbacks with 273 proc as NULL. 275 3.1.2. sasl_secret_t 277 The sasl_secret_t structure is used to hold text or binary passwords 278 for the client API. 280 typedef struct sasl_secret { 281 unsigned int len; 282 unsigned char data[1]; 283 } sasl_secret_t; 285 The len field holds the length of the password, while the data field 286 holds the actual data. The structure is variable sized: enough space 287 must be reserved after the data field to hold the desired password. 289 An additional '\0' character (not counted in len) is added at the 290 end. Note, however, that binary passwords are permitted to contain 291 '\0' characters. 293 3.1.3. sasl_conn_t 295 The sasl_conn_t data type is an opaque data type which reflects the 296 SASL context for a single server connection. Only one SASL API call 297 using a given sasl_conn_t as an argument may be active at a time. 298 However, each sasl_conn_t is independent and thus the SASL API may be 299 used in a true multi-processor multi-threaded environment. 301 3.1.4. sasl_interact_t 303 The sasl_interact_t structure is used by sasl_client_start and 304 sasl_client_step to request certain information from the application, 305 when the application did not provide corresponding callbacks. For 306 example, an application may choose to present a single dialog to the 307 user in order to collect all required information interactively. 309 typedef struct sasl_interact { 310 unsigned int id; 311 const char *challenge; 312 const char *prompt; 313 const char *defresult; 314 const void *result; 315 unsigned len; 316 } sasl_interact_t; 318 The id field holds the value of the callback ID. The prompt field 319 contains a string that should be presented to the user. If non-NULL, 320 challenge is a NUL-terminated string that will allow the user to 321 present a specific credential when prompted. This is different from 322 the prompt in that the prompt is more like a label for a text box 323 (for example "Response:" while challenge is a string that tells the 324 user what specifically is required by the response (for example, an 325 OTP challenge string). The defresult field contains a default value, 326 if any. Upon return from sasl_client_* the "result" field points to 327 the defresult. The client must present the information in the chal- 328 lenge and the prompt to the user and store the result and its length 329 in the result and the len fields respectively. 331 For example, SASL_CB_PASS interaction may contain the following 332 information: 333 id - SASL_CB_PASS 334 challenge - NULL 335 prompt - "Password:" 336 defresult - NULL (no default). 338 3.2. Basic SASL API Callback Routines 340 This section describes the basic callback functions needed for a sim- 341 ple client implementation. See the definition of sasl_callback_t in 342 section 3.1.1 for a description of the basic callback structure. 344 3.2.1. sasl_getsimple_t 346 Arguments: 347 void *context, 348 int id, 349 const char **result, 350 unsigned *len 352 Results: 353 SASL_OK -- success 354 SASL_FAIL -- error 356 This callback is used by the SASL API to request a simple constant 357 string from the application. This is used with id SASL_CB_USER 358 for the username, SASL_CB_AUTHNAME for the authentication name (if 359 different), and SASL_CB_LANGUAGE for a comma separated list of 360 [LANGTAGS] language tags. 362 The context is the context variable from the sasl_callback_t 363 structure, the id is the id from the sasl_callback_t structure, 364 and the callback is expected to set the result to a constant 365 string and the len to the length of that string. The result and 366 len parameters are never NULL. 368 3.2.2. sasl_getsecret_t 370 Arguments: 371 IN sasl_conn_t *conn, 372 IN void *context, 373 IN int id, 374 OUT sasl_secret_t **psecret 376 Results: 377 SASL_OK -- success 378 SASL_FAIL -- error 380 This callback is expected to create, prompt or locate a secret and 381 return the pointer to it in the psecret parameter. The secret MUST 382 persist till next call to this callback/sasl_dispose for the same 383 SASL connection. The conn argument is the connection context, the 384 context and id parameters are from the sasl_callback_t structure. 385 The id SASL_CB_PASS is used to request a clear text password. The 386 conn and the psecret parameters MUST NOT be NULL. 388 Returning SASL_OK with psecret set to NULL should indicate a user 389 desire to cancel the authentication sequence (e.g., user pressed 390 Cancel in a password dialog box). 392 3.2.3. sasl_getopt_t 394 Arguments: 395 void *context, 396 const char *plugin_name, 397 const char *option, 398 const char **result, 399 unsigned int *len 401 Results: 402 SASL_OK -- success 403 SASL_FAIL -- error 405 This callback is used by the SASL API to read options from the 406 application. This allows a SASL configuration to be encapsulated 407 in the caller's configuration system. Configuration items may be 408 mechanism-specific and are arbitrary strings. If the application 409 does not provide a sasl_getopt_t callback, then the API MAY obtain 410 configuration information from other sources, for example from a 411 default config file. 413 The context is the context variable from the sasl_callback_t 414 structure, the plugin_name is the name of plugin (or NULL), the 415 option is the option name, and the callback is expected to set the 416 result to a string valid till next call to sasl_getopt_t in the 417 same thread and the len to the length of that string. The result 418 and len parameters are never NULL. If the name of plugin is NULL, 419 a general SASL option is requested, otherwise a plugin specific 420 version. 422 3.3. Basic SASL API Client Routines 424 This section discusses the functions likely to be used by every 425 client caller of the SASL API. 427 3.3.1. sasl_client_init function 429 Arguments: 430 sasl_callback_t *callbacks 432 Results: 433 SASL_OK -- Success 434 SASL_NOMEM -- Not enough memory 435 SASL_BADVERS -- Mechanism version mismatch 436 SASL_BADPARAM -- Error in config file 438 This function initializes the client routines for the SASL API. 440 The callbacks argument is the default list of callbacks (see sec- 441 tion 3.1.1 for definition of sasl_callback_t structure). 442 Libraries that are clients of the API MUST supply NULL For this 443 parameter. Applications that are clients of the API MAY supply a 444 list that includes the sasl_getopt_t callback (see section 3.2.3), 445 but MUST NOT supply any other callbacks through this interface. An 446 application or library that needs to specify other callbacks shall 447 use prompt_supp parameter of the sasl_client_new (see section 448 3.3.2). 450 On success, SASL_OK is returned, and on failure a SASL C API error 451 code such as the ones listed above is returned. This function may 452 be called a second time to change the global sasl_getopt_t call- 453 back used for new connections, but the first call must be made in 454 a single-threaded environment. 456 There must be a call to sasl_done for every successful call to 457 sasl_server_init or sasl_client_init made. Each call to 458 sasl_server_init or sasl_client_init increment the internal refer- 459 ence counter. All but the last call to sasl_done descrement the 460 counter, the final sasl_done does the actual cleanup. The data 461 referenced by the sasl_callback_t structure must persist until the 462 very last call to sasl_done(). 464 3.3.2. sasl_client_new function 466 Arguments: 467 const char *service, 468 const char *server_name, 469 const char *iplocalport, 470 const char *ipremoteport, 471 const sasl_callback_t *prompt_supp, 472 unsigned int flags, 473 sasl_conn_t **pconn 475 Results: 476 SASL_OK -- Success 477 SASL_NOTINIT -- SASL API not initialized 478 SASL_NOMECH -- No mechanisms available 479 SASL_NOMEM -- Not enough memory 481 This function creates a client connection context variable. As 482 long as each thread uses its own connection context, the SASL C 483 API is thread-safe. 485 The service argument is an IANA registered GSSAPI service element 486 as defined in section 1.1. It MUST NOT be NULL. 488 The server_name is the host name or IP address of the server to 489 which the client is connecting. NULL may be used for server_name, 490 but may result in advanced mechanisms such as Kerberos being 491 unavailable. 493 The iplocalport is the string with the client IPv4/IPv6 address, 494 followed by ":" and than by port number. The syntax of IPv4/IPv6 495 addresses is defined by IPv4address/IPv6address ABNF elements from 496 [RFC 2373]. NULL may be used for iplocalport, but may result in 497 mechanisms requiring IP address being unavailable. 499 The ipremoteport is the string with the server IPv4/IPv6 address, 500 followed by ":" and than by port number. The syntax of IPv4/IPv6 501 addresses is defined by IPv4address/IPv6address ABNF elements from 502 [RFC 2373]. NULL may be used for ipremoteport, but may result in 503 mechanisms requiring IP address being unavailable. 505 User input to the SASL C API may be provided in two ways: either 506 by supplying callbacks (prompt_supp) to this function, or by using 507 an interaction model with the sasl_client_start/sasl_client_step 508 functions. Callbacks are more convenient to obtain information 509 programmatically, such as pulling authentication information 510 directly from a configuration file. Interactions are more conve- 511 nient if one wants to get all the data in parallel, for example by 512 displaying a single dialog box instead of a separate popup for 513 authentication name, authorization, password, etc. 515 The prompt_supp is a list of supported user prompting callbacks 516 discussed in the section 3.1.1. The prompt_supp argument MAY be 517 NULL, which means that interactions (i.e. prompt_need parameter to 518 sasl_client_start (see 3.3.3) and sasl_client_step (see 3.3.4)) 519 are used instead of callbacks. If prompt_supp is NULL, the 520 prompt_need argument to sasl_client_start (see 3.3.3) and 521 sasl_client_step (see 3.3.4) MUST NOT be NULL. 523 The prompt_supp argument may include a connection-specific 524 sasl_getopt_t callback. If a connection-specific sasl_getopt_t 525 callback is specified in the prompt_supp list, it will take prece- 526 dence over the global sasl_getopt_t callback specified in the last 527 sasl_client_init() call. 529 A SASL mechanism has a list of required callbacks. If all the 530 required callbacks are not provided by the calling application (or 531 not handled as interactions), the SASL mechanism is not going to 532 be selected. Thus it is necessary to list all callbacks that are 533 provided by the application and list all interactions as callbacks 534 with proc as NULL. 536 The flags argument represents client-supported security flags. 537 The value is a bitmask. Currently, only two values are defined: 538 SASL_SUCCESS_DATA and SASL_NEED_PROXY. 540 The SASL_SUCCESS_DATA flag specifies that the server (and the pro- 541 tocol) supports sending "additional data on success". This flag is 542 used by the SASL library to decide whether it can pass the success 543 data back along with SASL_OK, or if it must return SASL_CONTINUE 544 and then wait for an empty client response before returning 545 SASL_OK. 547 The SASL_NEED_PROXY flag tells the SASL library that it must only 548 select mechanisms that support proxy authorization. 550 The pconn argument is set to point to the newly created connection 551 context. The sasl_conn_t type is opaque to the calling applica- 552 tion. 554 3.3.3. sasl_client_start function 556 Arguments: 557 sasl_conn_t *conn, 558 const char *mechlist, 559 sasl_interact_t **prompt_need, 560 const char **clientout, 561 unsigned int *clientoutlen, 562 const char **mech 564 Results: 565 SASL_NOTINIT -- SASL API not initialized 566 SASL_BADPARAM -- conn or mechlist is NULL 567 SASL_NOMECH -- No matching mechanisms available 568 SASL_NOMEM -- Not enough memory 569 SASL_INTERACT -- User interaction needed to continue 570 (see prompt_need description below) 571 SASL_OK -- Success 573 This selects an authentication mechanism to use and optionally 574 generates an initial client response. 576 The conn argument is the connection context from sasl_client_new. 578 The mechlist argument is a '\0' terminated string containing one 579 or more SASL mechanism names. All characters in the string that 580 are not permitted in a SASL mechanism name [SASL] are ignored 581 except for the purposes of delimiting mechanism names (this per- 582 mits passing direct results from many protocol capability lists 583 unparsed). Unknown mechanism names are ignored (although 584 SASL_NOMECH is returned if no known mechanisms are found). Mecha- 585 nisms are tried in an implementation-dependent order. Implementa- 586 tions SHOULD try to use the most secure mechanism possible, within 587 the constraints specified by the application (e.g. SSF value). If 588 the application wants to control which mechanism from the list 589 would be selected, it has to break the list apart and call the 590 function by passing a single SASL mechanism name at a time in the 591 mech_list parameter. 593 For applications which support interactions, the prompt_need argu- 594 ment should initially point to a NULL pointer. If the selected 595 mechanism needs information from the user (for example, username 596 or password), then prompt_need will be set to point to an array of 597 sasl_interact_t structures (terminated by an entry with id equal 598 to SASL_CB_LIST_END), and sasl_client_start will return 599 SASL_INTERACT. After that the client must fill in the requested 600 information and call this function again with the same parameters. 602 Applications that do not support interactions MUST pass NULL for 603 prompt_need. 605 The clientout and clientoutlen parameters are set to the initial 606 client response, if any. If a protocol's SASL profile uses base64 607 encoding, this represents the data prior to the encoding (see 608 sasl_encode64). If a protocol's SASL profile doesn't include an 609 optional initial client response, then these may be NULL and 0 610 respectively. The memory used by clientout is interally managed by 611 the SASL API and may be overwritten on the next call to 612 sasl_client_step or a call to sasl_dispose. 614 The mech argument is set to point to a '\0' terminated string 615 specifying the mechanism actually selected using all uppercase 616 letters. It may be NULL if the client does not care which mecha- 617 nism was selected from mechlist. 619 If sasl_client_start is called a second time using the same con- 620 nection context, it will discard any cached information (e.g., the 621 username and password) and restart the exchange as if this were 622 the first call to the sasl_client_start. 624 3.3.4. sasl_client_step function 626 Arguments: 627 sasl_conn_t *conn, 628 const char *serverin, 629 unsigned int serverinlen, 630 sasl_interact_t **prompt_need, 631 const char **clientout, 632 unsigned int *clientoutlen 634 Results: 635 SASL_NOTINIT -- SASL API not initialized 636 SASL_NOMECH -- sasl_client_start not called 637 SASL_BADPROT -- server protocol incorrect/cancelled 638 SASL_BADSERV -- server failed mutual auth 639 SASL_INTERACT -- user interaction needed 640 SASL_OK -- success 642 This routine performs one step in an authentication sequence. 644 The conn argument must be a connection context created by 645 sasl_client_new and used in a previous call to sasl_client_start. 647 The serverin and serverinlen parameters hold the SASL octet string 648 received from the server. Note that for those SASL profiles which 649 base64 encode the exchange, this is the result after the removal 650 of the base64 encoding (see the sasl_decode64 routine below). The 651 serverin may contain arbitrary binary data, in particular it MAY 652 contain one or more NUL characters. The serverin MUST have a 653 terminating NUL character not counted by serverinlen. 655 The prompt_need argument is the same as for sasl_client_start. 657 The clientout and clientoutlen parameters hold the SASL octet 658 string to encode (if necessary) and send to the server. 660 3.4. Basic SASL C API Server Routines 662 This section describes the basic routines for a server implementa- 663 tion of a SASL profile. 665 3.4.1. sasl_server_init function 667 Arguments: 668 const sasl_callback_t *callbacks, 669 const char *appname 671 Results: 672 SASL_BADPARAM -- error in config file 673 SASL_NOMEM -- out of memory 674 SASL_BADVERS -- Plug-in version mismatch 675 SASL_OK -- success 677 This function initializes the server routines for the SASL C API. 679 The callbacks argument is the default list of callbacks (see sec- 680 tion 3.1.1 for definition of sasl_callback_t structure). 681 Libraries that are clients of the API MUST supply NULL for this 682 parameter. Applications that are clients of the API MAY supply a 683 list that includes the sasl_getopt_t callback (see section 3.2.3), 684 but MUST NOT supply any other callbacks through this interface. An 685 application or library that needs to specify other callbacks shall 686 use callbacks parameter of the sasl_server_new (see section 687 3.4.2). 689 The appname argument is the name of the calling application. SASL 690 API may use it, for example, for logging or to read an application 691 specific configuration. A library must pass NULL as appname. app- 692 name can be also be set with sasl_setprop function, and can be 693 queried with sasl_getprop. The corresponding constant for the app- 694 name option is SASL_APPNAME. 696 On success, SASL_OK is returned, and on failure a SASL C API error 697 code is returned. This function may be called a second time to 698 change the global sasl_getopt_t callback used for new connections, 699 but the first call must be made in a single-threaded environment. 701 There must be a call to sasl_done for every successful call to 702 sasl_server_init or sasl_client_init made. Each call to 703 sasl_server_init or sasl_client_init increment the internal refer- 704 ence counter. All but the last call to sasl_done descrement the 705 counter, the final sasl_done does the actual cleanup. The data 706 referenced by the sasl_callback_t structure must persist until the 707 very last call to sasl_done(). 709 3.4.2. sasl_server_new function 711 Arguments: 712 IN const char *service, 713 IN const char *serverFQDN, 714 IN const char *user_realm, 715 IN const char *iplocalport, 716 IN const char *ipremoteport, 717 IN const sasl_callback_t *callbacks, 718 In unsigned int flags, 719 OUT sasl_conn_t **pconn 721 Results: 722 SASL_OK -- success 723 SASL_NOTINIT -- SASL API not initialized 724 SASL_BADPARAM -- Invalid parameter supplied 725 SASL_NOMECH -- No mechanisms available 726 SASL_NOMEM -- Not enough memory 728 This function creates a server connection context variable. As 729 long as each thread uses its own connection context, the SASL C 730 API is thread-safe. 732 The service argument is an IANA registered GSSAPI service element 733 as defined in section 1.1. It MUST NOT be NULL. 735 The serverFQDN is the fully qualified name of the server. It 736 SHOULD NOT be NULL. If it is NULL, the SASL library can default 737 the value in the implementation defined manner, e.g. the library 738 MAY use a value stored in a configuration file or the result of 739 gethostname() or a similar call. 741 The user_realm specifies the default realm. A realm defines a set 742 of users on the system for systems which support multiple user 743 communities ("realms"). If user_realm is NULL, the value of 744 serverFQDN is used as the default realm. (If serverFQDN is also 745 NULL, it is assumed that it has the value defaulted as described 746 above.) 748 The iplocalport is the string with the server IPv4/IPv6 address, 749 followed by ":" and than by the port number. The syntax of 750 IPv4/IPv6 addresses is defined by IPv4address/IPv6address ABNF 751 elements from [RFC 2373]. NULL may be used for iplocalport, but 752 may result in mechanisms requiring IP address being unavailable. 754 The ipremoteport is the string with the client IPv4/IPv6 address, 755 followed by ":" and than by the port number. The syntax of 756 IPv4/IPv6 addresses is defined by IPv4address/IPv6address ABNF 757 elements from [RFC 2373]. NULL may be used for ipremoteport, but 758 may result in mechanisms requiring IP address being unavailable. 760 The callbacks argument is a set of server callbacks which may 761 include a connection-specific sasl_getopt_t. If a connection-spe- 762 cific sasl_getopt_t callback is specified in callbacks list, it 763 will take precedence over the global sasl_getopt_t callback speci- 764 fied in the last sasl_server_init() call. 766 The flags argument represents server-supported security flags. 767 The value is a bitmask. Currently, only two values are defined: 768 SASL_SUCCESS_DATA and SASL_NEED_PROXY. 770 The SASL_SUCCESS_DATA flag specifies that the server (and the pro- 771 tocol) supports sending "additional data on success". This flag is 772 used by the SASL library to decide whether it can pass the success 773 data back along with SASL_OK, or if it must return SASL_CONTINUE 774 and then wait for an empty client response before returning 775 SASL_OK. 777 Even if SASL_SUCCESS_DATA is specified, the server MUST check the 778 serverout pointer it receives from sasl_server_step() to see if it 779 non-null, because some mechs only have success data in certain 780 cases (ie, SRP with SSF==0). 782 The SASL_NEED_PROXY flag tells the SASL library that it must only 783 select mechanisms that support proxy authorization. 785 The pconn argument is set to point to the newly created connection 786 context. 788 3.4.3. sasl_server_start function 790 Arguments: 791 sasl_conn_t *conn, 792 const char *mech, 793 const char *clientin, 794 insigned int clientinlen, 795 const char **serverout, 796 unsigned int *serveroutlen 798 Results: 799 SASL_CONTINUE -- Another authentication step required 800 SASL_OK -- Authentication Complete 801 SASL_NOTINIT -- SASL API not initialized 802 SASL_BADPARAM -- Invalid parameter supplied 803 SASL_BADPROT -- Client protocol error 804 SASL_NOMECH -- Mechanism not supported 805 SASL_NOVERIFY -- User exists, but no verifier exists for 806 the mechanism 807 SASL_TRANS -- A password transition is needed to use mechanism 809 This begins an authentication exchange and is called after the 810 client sends the initial authentication command. The mech argu- 811 ment is the mechanism name the client is requesting. If the 812 client includes an optional initial-response, it is passed in the 813 clientin and clientinlen fields. Otherwise NULL and 0 are passed 814 for those arguments. The serverout and serveroutlen are filled in 815 with the server response, if any. If SASL_CONTINUE is returned, 816 the server will need to wait for another client message and call 817 sasl_server_step. If SASL_OK is returned, the authentication is 818 completed successfully, although serverout may be supplied. 820 <<...Does this work for the server side?...>> If sasl_server_start 821 is called a second time using the same connection context, it will 822 discard any cached information (e.g., the username and password) 823 and restart the exchange as if this were the first call to the 824 sasl_server_start. 826 3.4.4. sasl_server_step function 828 Arguments: 829 sasl_conn_t *conn, 830 const char *clientin, 831 insigned int clientinlen, 832 const char **serverout, 833 unsigned int *serveroutlen 835 Results: 836 SASL_CONTINUE -- Another authentication step required 837 SASL_OK -- Authentication Complete 838 SASL_NOTINIT -- SASL API not initialized 839 SASL_NOMECH -- sasl_server_start not called 840 SASL_BADPARAM -- Invalid parameter supplied 841 SASL_BADPROT -- Client protocol error 842 SASL_NOVERIFY -- User exists, but no verifier exists for 843 the mechanism 844 SASL_TRANS -- A password transition is needed to use mechanism 846 This routine performs one step in an authentication sequence. 848 The conn argument must be a connection context created by 849 sasl_server_new and used in a previous call to sasl_server_start. 851 The clientin and clientinlen parameters hold the SASL octet string 852 received from the client. Note that for those SASL profiles which 853 base64 encode the exchange, this is the result after the removal 854 of the base64 encoding (see the sasl_decode64 routine). The cli- 855 entin may contain arbitrary binary data, in particular it MAY con- 856 tain one or more NUL characters. The clientin MUST have a termi- 857 nating NUL character not counted by serverinlen. 859 The serverout and serveroutlen parameters hold the SASL octet 860 string to encode (if necessary) and send to the client. If 861 SASL_CONTINUE is returned, the server will need to wait for 862 another client message and call sasl_server_step. If SASL_OK is 863 returned, the authentication is completed successfully, although 864 server out data may be supplied. 866 3.5. Common SASL API Routines 868 This section describes the routines that are common to both 869 clients and servers. 871 3.5.1. sasl_listmech function 873 Arguments: 874 sasl_conn_t *conn, 875 const char *user, 876 const char *prefix, 877 const char *sep, 878 const char *suffix, 879 char **result, 880 unsigned int *plen, 881 unsigned *pcount 883 Results: 884 SASL_OK -- Success 885 SASL_NOMEM -- Not enough memory 886 SASL_NOMECH -- No enabled mechanisms 888 This returns a list of enabled SASL mechanisms in a NUL-terminated 889 string. The list is constructed by placing the prefix string at 890 the beginning, placing the sep string between any pair of mecha- 891 nisms and placing the suffix string at the end. 893 When calling this function plen and pcount MAY be NULL. 895 This function returns the list of the client side SASL mechanisms, 896 if the conn was created by sasl_client_new and the list of the 897 server side mechanisms, if the conn was created by 898 sasl_server_new. The list returned by this function must persist 899 till a next call to sasl_free_listmech or sasl_listmech. 901 3.5.2. sasl_free_listmech function 903 Arguments: 904 sasl_conn_t *conn, 905 char **result 907 Results: 908 none 910 This disposes of the result string returned by sasl_listmech. 912 3.5.3. sasl_setprop function 914 Arguments: 915 sasl_conn_t *conn, 916 int propnum, 917 const void *value 919 Results: 920 SASL_OK -- property set 921 SASL_BADPARAM -- invalid propnum or value or connection is NULL 922 SASL_BADPROT -- the property is not settable for this type of connection 923 SASL_NOMEM -- not enough memory to perform operation 925 This sets a property in a connection context. Commonly used prop- 926 erties with their descriptions are listed below: 928 SASL_SSF_EXTERNAL 930 Security layer strength factor (SSF) -- an unsigned integer usable 931 by the caller to specify approximate security layer strength 932 desired. It roughly corresponds to the effective key length for 933 encryption, e.g. 934 0 = no protection 935 1 = integrity protection only >1 = key lenght of the cipher 937 SASL_SSF_EXTERNAL property denotes SSF of the external security 938 layer (e.g. provided by TLS). The value parameter points to 939 sasl_ssf_t, that is described as follows: 941 typedef unsigned sasl_ssf_t; 943 SASL_SEC_PROPS 945 The value parameter for SASL_SEC_PROPS points to sasl_secu- 946 rity_properties_t structure defined below. A particular implemen- 947 tation may extend it with additional fields. 949 typedef struct sasl_security_properties 950 { 951 sasl_ssf_t min_ssf; 952 sasl_ssf_t max_ssf; 954 unsigned maxbufsize; 956 /* bitfield for attacks to protect against */ 957 unsigned security_flags; 958 } sasl_security_properties_t; 959 The min_ssf and the max_ssf define the minimal and the maximal 960 acceptable SSF. 962 The maxbufsize specifies the biggest buffer size that the 963 client/server is able to decode. 0 means that security layer is 964 not supported. 966 The security_flags is a bitmask of the various security flags 967 described below: 969 SASL_SEC_NOPLAINTEXT -- don't permit mechanisms susceptible to simple 970 passive attack (e.g., PLAIN, LOGIN) 971 SASL_SEC_NOACTIVE -- protection from active (non-dictionary) attacks 972 during authentication exchange. 973 Authenticates server. 974 SASL_SEC_NODICTIONARY -- don't permit mechanisms susceptible to passive 975 dictionary attack 976 SASL_SEC_FORWARD_SECRECY -- require forward secrecy between sessions 977 (breaking one won't help break next) 978 SASL_SEC_NOANONYMOUS -- don't permit mechanisms that allow anonymous login 979 SASL_SEC_PASS_CREDENTIALS -- require mechanisms which pass client 980 credentials, and allow mechanisms which can pass 981 credentials to do so 982 SASL_SEC_MUTUAL_AUTH -- require mechanisms which provide mutual 983 authentication 985 SASL_AUTH_EXTERNAL 987 The value parameter for SASL_AUTH_EXTERNAL property points to the 988 external authentication ID as provided by external authentication 989 method, e.g. TLS, PPP or IPSec. 991 Full list of properties is provided in section 6. 993 3.5.4. sasl_getprop function 995 Arguments: 996 sasl_conn_t *conn, 997 int propnum, 998 const void **pvalue 1000 Results: 1001 SASL_OK -- Success 1002 SASL_NOTDONE -- Authentication exchange must complete prior to 1003 retrieving this attribute 1004 SASL_BADPARAM -- bad property number or invalid connection type 1005 SASL_BADPROT -- the property is not readable for this type of connection 1007 This requests a pointer to a constant property available through 1008 the SASL API. The most common use by servers is to get the 1009 SASL_USERNAME property which returns the authorization identity 1010 (user to login as) from the SASL mechanism as a UTF-8 string in 1011 the pvalue parameter. Full list of properties is provided in sec- 1012 tion 6. 1014 3.5.5. sasl_dispose function 1016 Arguments: 1017 sasl_conn_t **pconn 1019 Results: 1020 none 1022 This function disposes of the connection state created with 1023 sasl_client_new or sasl_server_new, and sets the pointer to NULL. 1024 If the pconn is already NULL the function does nothing. 1026 3.5.6. sasl_done function 1028 Arguments: 1029 none 1031 Results: 1032 <> 1036 A SASL application that is finished with the SASL API must call 1037 this function. This function frees any memory allocated by the 1038 SASL library or any other library state. After this call most of 1039 the SASL API function will again return the SASL_NOTINIT error 1040 code. 1042 There must be a call to sasl_done for every successful call to 1043 sasl_server_init or sasl_client_init made. Only the final 1044 sasl_done does the actual cleanup; the preceding calls simply 1045 decrement an internal reference count. 1047 Connection states MUST be disposed of with sasl_dispose before 1048 calling this function. 1050 3.5.7. sasl_version_info function 1052 Arguments: 1053 const char **implementation, 1054 const char **version_string, 1055 int *version_major, 1056 int *version_minor, 1057 int *version_step, 1058 int *version_patch 1060 Results: 1061 none 1063 This function returns a string identifying a particular implemen- 1064 tation of the SASL C API (implementation parameter) and a vendor 1065 specific version number. This function can be used for library 1066 version display and logging. It may be also used for bug 1067 workarounds in old library versions. This funtion should not to be 1068 used for API feature detection. 1070 The vendor specific version number is returned in a string form in 1071 the version_string parameter. Specific components of the version 1072 number are returned in version_major, version_minor, version_step 1073 and version_patch. Note, that a particular SASL implementation may 1074 choose not to use a version component, for example the ver- 1075 sion_patch. In this case the function should always return 0 in 1076 such parameter. 1078 All parameters of this function are optional. If NULL is speci- 1079 fied, the value is not returned. 1081 The implementation and the version_string strings are not allo- 1082 cated and must not be freed. 1084 3.5.8. sasl_errstring function 1086 Arguments: 1087 int saslerr, 1088 const char *langlist, 1089 const char **outlang 1091 Results: 1092 const char * 1094 This converts a SASL error number into a constant string. The 1095 second argument MAY be NULL for the default language, or a comma- 1096 separated list of [LANGTAGS] language tags. The final parameter 1097 is set (if not NULL) to the [LANGTAGS] language tag of the string 1098 returned which will be "i-default" if no matching language is 1099 found. The strings are UTF-8. This requires no context so it may 1100 be used for the result of an sasl_*_init or sasl_*_new result 1101 code. 1103 3.5.9. sasl_errdetail function 1105 Arguments: 1106 sasl_conn_t *conn 1108 Results: 1109 const char * 1111 This function returns a human readable string that corresponds to 1112 the last SASL error that occured on the connection. The string 1113 MUST be in UTF8. This string is suitable to be passed back over 1114 the protocol and presented to an end-user. Thus, it must not leak 1115 a security sensitive information, e.g. it must not show the dis- 1116 tinction between "user not found" and "bad password". 1118 The function must use the SASL_CB_LANGUAGE callback (see section 1119 3.2.1) to determine the language to use. It may return more 1120 detailed information than sasl_errstring does. 1122 3.5.10. sasl_seterror function 1124 Arguments: 1125 sasl_conn_t *conn 1126 unsigned flags, 1127 const char *fmt, 1128 ... 1130 Results: 1131 none 1133 This function sets the error string which will be returned by 1134 sasl_errdetail. It uses syslog()-style formatting (i.e. printf- 1135 style with %m as the string form of the errno error). 1137 Messages should be sensitive to the current language setting. If 1138 there is no SASL_CB_LANGUAGE callback for the connection, text 1139 MUST be in US-ASCII. Otherwise UTF-8 is used and use of RFC 2482 1140 for mixed-language text is encouraged. 1142 The resulting formatted string should be stored in connection con- 1143 text until connection context is destroyed or a next call to 1144 sasl_seterror() <>. 1147 The flags parameter can be either 0 or SASL_NOLOG. If the flags 1148 parameter is 0, upon formatting the error message the sasl_seter- 1149 ror will call the SASL logging callback (if any) with a level of 1150 SASL_LOG_FAIL. <> 1152 This function may be used by server callbacks. 1154 If conn is NULL, the function does nothing. 1156 3.6. Basic SASL C API Utility Routines 1158 This section describes utility functions provided as part of the 1159 SASL API which may be used both by clients and servers. 1161 3.6.1. sasl_decode64 function 1163 Arguments: 1164 const char *in, 1165 unsigned int inlen, 1166 char *out, 1167 unsigned int outmax, 1168 unsigned int *outlen 1170 Results: 1171 SASL_BUFOVER -- output buffer too small 1172 SASL_BADPROT -- invalid base64 string 1173 SASL_OK -- successful decode 1175 This utility routine converts a base64 string of length inlen 1176 pointed by in into an octet string. It is useful for SASL profiles 1177 which use base64 such as the IMAP [IMAP4] and POP [POP-AUTH] pro- 1178 files. The output is copied to the buffer specified by the out 1179 parameter. It is NUL terminated and the length of the output is 1180 placed in the outlen parameter if outlen is non-NULL. The lenght 1181 doesn't include the terminating NUL character. 1183 When the size of the output buffer, as specified by outmax, is too 1184 small, the function returns SASL_BUFOVER error code and the 1185 required length is stored in the outlen parameter if it is not 1186 NULL. 1188 The function may also return SASL_BADPROT error code when it 1189 encounters an invalid base64 character. 1191 3.6.2. sasl_encode64 function 1193 Arguments: 1194 const char *in, 1195 unsigned int inlen, 1196 char *out, 1197 unsigned int outmax, 1198 unsigned int *outlen 1200 Results: 1201 SASL_BUFOVER -- output buffer too small 1202 SASL_OK -- successful decode 1204 This utility routine converts an octet string of length inlen 1205 pointed by in into a base64 string. It is useful for SASL profiles 1206 which use base64 such as the IMAP [IMAP4] and POP [POP-AUTH] pro- 1207 files. 1209 The output is copied to the buffer specified by the out parameter. 1210 It is NUL terminated and the length of the output is placed in the 1211 outlen parameter if outlen is non-NULL. The lenght doesn't include 1212 the terminating NUL character. 1214 When the size of the output buffer, as specified by outmax, is too 1215 small, the function returns SASL_BUFOVER error code and the 1216 required length is stored in the outlen parameter if it is not 1217 NULL. 1219 3.6.3. sasl_erasebuffer function 1221 Arguments: 1222 char *buf, 1223 unsigned len 1225 Results: 1226 none 1228 This function fills the buffer buf of the length len with '\0' 1229 characters. The function may be used to clear from memory sensi- 1230 tive informations, like passwords. 1232 3.6.4. sasl_utf8verify function 1234 Arguments: 1235 const char *str, 1236 unsigned len 1238 Results: 1239 SASL_BADPROT -- the input string is not a valid UTF-8 string 1240 SASL_OK -- the input string is a valid UTF-8 string 1242 This function verifies if the str is a valid UTF-8 string. If the 1243 len is 0, the length of the string is determined by calling 1244 strlen(str). 1246 4. SASL Security Layer Routines 1248 This section describes the routines need to support a security 1249 layer. 1251 4.1. sasl_encode function 1253 Arguments: 1254 sasl_conn_t *conn, 1255 const char *input, 1256 unsigned int inputlen, 1257 const char **output, 1258 unsigned int *outputlen 1260 Results: 1261 SASL_OK -- Success (returns input if no layer was negotiated) 1262 SASL_NOTDONE -- Security layer negotiation is not yet finished 1263 SASL_BADPARAM -- inputlen is greater than the SASL_MAXOUTBUF property, 1264 or a parameter is invalid (i.e. conn is NULL, input 1265 or output is NULL). 1266 <> 1268 This function encodes a block of data for transmission using secu- 1269 rity layer (if any). The output and outputlen are filled in with 1270 the encoded data and its length respectively. If there is no secu- 1271 rity layer the input buffer is returned in the output. Otherwise, 1272 the output is only valid until a next call to sasl_encode, 1273 sasl_encodev or sasl_dispose. 1275 Both sides of the connection should follow the following guide- 1276 lines 1278 * Before starting authentication, the application should set 1279 the maxbufsize field in the sasl_security_properties_t 1280 to be the buffer size that the application passes to 1281 the read() system call, i.e. the amount of data that the 1282 application is prepared to read at any one time. 1283 After that the application should use sasl_setprop() with 1284 the property index of SASL_SEC_PROPS to notify SASL API 1285 about the choice. 1287 * After authentication finishes, the application should use 1288 sasl_getprop() to retrieve the SASL_MAXOUTBUF value, and call 1289 sasl_encode() with chunks of data of that size or less. 1290 sasl_encode() will return SASL_BADPARAM if it is called 1291 with a larger chunk of data. 1293 4.2. sasl_encodev function 1295 Arguments: 1296 sasl_conn_t *conn, 1297 const struct iovec *invec, 1298 unsigned int numiov, 1299 const char **output, 1300 unsigned int *outputlen 1302 Results: 1303 SASL_OK -- Success (returns input if no layer was negotiated) 1304 SASL_NOTDONE -- Security layer negotiation is not yet finished 1305 SASL_BADPARAM -- inputlen is greater than the SASL_MAXOUTBUF property, 1306 or a parameter is invalid (i.e. conn is NULL, input 1307 or output is NULL). 1308 <> 1310 This function encodes one or more block of data for transmission 1311 using security layer (if any). The output and outputlen are filled 1312 in with the encoded data and its length respectively. <> 1314 Otherwise, the output is only valid until a next call to 1315 sasl_encode, sasl_encodev or sasl_dispose. 1317 The invec parameter is an array of iovec structures defined as 1318 follows: 1320 struct iovec { 1321 long iov_len; 1322 char *iov_base; 1323 }; 1325 where iov_base is a pointer to a block of data to be encoded and 1326 iov_len is the length of the block. This is the same structure 1327 that is used by writev() function on many Unix systems. 1329 The number of data blocks in invec is specified by the numiov 1330 parameter. 1332 See also note in section 4.1 about use of this function. 1334 4.3. sasl_decode function 1336 Arguments: 1337 sasl_conn_t *conn, 1338 const char *input, 1339 unsigned int inputlen, 1340 const char **output, 1341 unsigned int *outputlen 1343 Results: 1344 SASL_OK -- Success (returns input if no layer was negotiated) 1345 SASL_NOTDONE -- Security layer negotiation is not yet finished 1346 SASL_BADMAC -- Bad message integrity check 1347 SASL_BADPARAM -- A parameter is invalid (i.e. conn is NULL, input 1348 or output is NULL). 1350 This function decodes a block of data received using security 1351 layer (if any). The output and outputlen are filled in with the 1352 decoded data and its length respectively. If there is no security 1353 layer the input buffer is returned in the output. Otherwise, the 1354 output is only valid until a next call to sasl_decode or sasl_dis- 1355 pose. 1357 If the input contains more than one SASL token, sasl_decode MUST 1358 concatenate the decoded data together. If the input contains one 1359 or more SASL tokens and a few bytes of a subsequent SASL token, 1360 sasl_decode MUST save the beginning of the uncomplete token in the 1361 conn and use the saved data when the sasl_decode is called the 1362 next time. Because all SASL mechanisms MUST negotiate or declare 1363 the maximal token size, preallocated buffer inside sasl_conn_t can 1364 be used for this. 1366 5. Advanced SASL API Routines 1368 This section describes the less frequently used functions avail- 1369 able in the SASL API. 1371 5.1. Additional Initialization Routines 1373 5.1.1. sasl_set_mutex function 1375 Arguments: 1376 sasl_mutex_alloc_t *mutex_alloc, 1377 sasl_mutex_lock_t *mutex_lock, 1378 sasl_mutex_unlock_t *mutex_unlock, 1379 sasl_mutex_free_t *mutex_free 1381 Results: 1382 None 1384 The sasl_set_mutex call sets the callbacks which the SASL API and 1385 plug-ins will use whenever exclusive access to a process shared 1386 resource is needed. A single-threaded client or server need not 1387 call this. The types are designed to be compatible with the LDAP 1388 API [LDAP-API]: 1390 typedef void *sasl_mutex_alloc_t(void); 1392 On success, this returns a pointer to an allocated and initialized 1393 mutex structure. On failure, it returns NULL. 1395 typedef int sasl_mutex_lock_t(void *mutex); 1397 This will block the current thread until it is possible to get an 1398 exclusive lock on a mutex allocated by the mutex_alloc callback. 1399 On success it returns 0, on failure due to deadlock or bad parame- 1400 ter, it returns -1. 1402 typedef int sasl_mutex_unlock_t(void *mutex); 1404 This releases a lock on a mutex allocated by the mutex_alloc call- 1405 back. On success it returns 0, on failure due to an already 1406 unlocked mutex, or bad parameter, it returns -1. 1408 typedef void sasl_mutex_free_t(void *mutex); 1410 This disposes of a mutex allocated by mutex_alloc. 1412 5.1.2. sasl_set_alloc function 1414 Arguments: 1415 sasl_malloc_t *malloc, 1416 sasl_calloc_t *calloc, 1417 sasl_realloc_t *realloc, 1418 sasl_free_t *free 1420 Results: 1421 None 1423 This sets the memory allocation functions which the SASL API will 1424 use. The SASL API will use its own routines (usually the standard 1425 C library) if these are not set. 1427 typedef void *sasl_malloc_t(unsigned long mem_size); 1429 This allocates memory mem_size bytes of memory. The memory is not 1430 initialized to any particular value. It returns NULL on a fail- 1431 ure, or when mem_size is 0. 1433 typedef void *sasl_calloc_t(unsigned long elem_size, 1434 unsigned long num_elem); 1436 This allocates elem_size * num_elem bytes of memory. The memory 1437 is initialized to 0. It returns NULL on a failure or when either 1438 elem_size and/or num_elem is 0. 1440 typedef void *sasl_realloc_t(void *mem_ptr, unsigned long 1441 new_size); 1443 This changes the size of a memory block previously allocated by 1444 malloc or calloc, and returns a pointer to the new location (which 1445 may be different from mem_ptr). If mem_ptr is NULL, it is identi- 1446 cal to the malloc function. 1448 It returns NULL on a failure or when new_size is 0. On failure the 1449 original block is unchanged. When new_size is 0 the function works 1450 as the free function. 1452 typedef void sasl_free_t(void *mem_ptr); 1454 This releases the memory in mem_ptr that was allocated by the mal- 1455 loc or the calloc or resized by the realloc. If mem_ptr is NULL, 1456 the function does nothing and returns immediately. The contents of 1457 the memory may be altered by this call. 1459 6. Standard Properties 1461 r/o - read only 1462 r/w - read-write 1463 server - server side only 1465 SASL_USERNAME -- (r/o) pointer to NUL terminated user name (authorization id) 1466 SASL_SSF -- (r/o) security layer security strength factor, 1467 if 0, call to sasl_encode, sasl_decode unnecessary 1468 SASL_MAXOUTBUF -- (r/o) security layer maximal output buffer size, unsigned. 1469 Use maxbufsize field in sasl_security_properties_t structure 1470 (settable as SASL_SEC_PROPS property) to set required maximal 1471 output buffer size before starting a SASL authentication. 1472 The value returned by SASL_MAXOUTBUF may differ (be less) from 1473 the value specified in maxbufsize field. 1474 SASL_DEFUSERREALM -- (r/w, server) default realm passed to sasl_server_new or set with 1475 sasl_setprop 1476 SASL_GETOPTCTX -- (r/o) context for getopt callback 1477 SASL_CALLBACK -- (r/o) current callback function list 1478 SASL_IPLOCALPORT -- (r/w) iplocalport string passed to sasl_server_new/ 1479 sasl_client_new or set with sasl_setprop. 1480 SASL_IPREMOTEPORT -- (r/w) ipremoteport string passed to sasl_server_new/ 1481 sasl_client_new or set with sasl_setprop. 1482 SASL_PLUGERR -- (r/o) a string which is either empty or has an error message 1483 from the sasl_seterror (e.g., from a plug-in or callback). 1484 It differs from the result of sasl_errdetail() which also takes 1485 into account the last return status code. 1486 SASL_SERVICE -- (r/o) service passed to sasl_*_new 1487 SASL_SERVERFQDN -- (r/o) serverFQDN passed to sasl_*_new 1488 SASL_AUTHSOURCE -- (r/o) name of the active plugin, if any. 1489 If the implementation of SASL API doesn't support plugins, 1490 it SHOULD return the name of the active SASL mechanism (if any). 1491 If no mechanism name is available, sasl_getprop should fail 1492 with SASL_NOTDONE error code. 1493 SASL_MECHNAME -- (r/o) active SASL mechanism name, if any 1494 SASL_AUTHUSER -- (r/o) pointer to a NUL terminated authentication/admin user 1495 (authentication id). 1496 SASL_APPNAME -- (r/w) name of the calling application. 1497 This name can be used for logging purposes and/or to construct 1498 the name of the configuration file. This property is available 1499 to both server and client applications. 1500 When a server application specifies an non NULL appname parameter 1501 in a call to sasl_server_init function, a SASL API implementation 1502 MUST call sasl_setprop internally with the appname as the value 1503 for the SASL_APPNAME property. 1504 SASL_SSF_EXTERNAL -- (r/w) pointer to an unsigned integer that denotes SSF provided 1505 by an external security layer (e.g. TLS). See section 3.5.3 for 1506 more details. 1507 SASL_SEC_PROPS -- (r/w) pointer to sasl_security_properties_t. See section 3.5.3 1508 for detailed description. 1509 SASL_AUTH_EXTERNAL-- (r/w) pointer to a NUL terminated authentication id provided by 1510 an external security layer (e.g. TLS). See section 3.5.3 for 1511 more details. 1513 7. References 1515 7.1. Normative References 1517 [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate 1518 Requirement Levels", RFC 2119, Harvard University, March 1997. 1520 [SASL] Myers, J., "Simple Authentication and Security Layer 1521 (SASL)", RFC 2222, Netscape Communications, October 1997. 1522 <> 1524 [RFC 2373] Hinden, R., Deering, S., "IP Version 6 Addressing 1525 Architecture", RFC 2373, July 1998. 1527 [LANGTAGS] Alvestrand, H., "Tags for the Identification of Lan- 1528 guages", RFC 3066, Cisco Systems, January 2001. 1530 7.2. Informative References 1532 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 1533 4rev1", RFC 3501, University of Washington, March 2003. 1535 [POP-AUTH] Myers, "POP3 AUTHentication command", RFC 1734, 1536 Carnegie Mellon, December 1994. 1538 [GSSAPI] Linn, J., "Generic Security Service Application Program 1539 Interface Version 2, Update 1", RFC 2743, January 2000. 1541 [LDAP] <<>> 1543 8. Acknowledgements 1545 The editor would like to thank Rob Siemborski, Ken Murchison, 1546 Philip Guenther, Randy Presuhn, Simon Josefsson, Lawrence Green- 1547 field and Greg Hudson for providing useful feedback and sugges- 1548 tions. 1550 9. Author's and Editor's Addresses 1552 Author: 1554 Chris Newman 1555 Sun Microsystems 1556 1050 Lakes Drive 1557 West Covina, CA 91790 USA 1559 Email: Chris.Newman@Sun.COM 1561 Editor: 1563 Alexey Melnikov 1564 Isode Ltd. 1565 5 Castle Business Village, 1566 36 Station Road, 1567 Hampton, Middlesex, 1568 United Kingdom, TW12 2BX 1570 Email: alexey.melnikov@isode.com 1572 10. Full Copyright Statement 1574 Copyright (C) The Internet Society (2004). All Rights Reserved. 1576 This document and translations of it may be copied and furnished to 1577 others, and derivative works that comment on or otherwise explain it 1578 or assist in its implementation may be prepared, copied, published 1579 and distributed, in whole or in part, without restriction of any 1580 kind, provided that the above copyright notice and this paragraph are 1581 included on all such copies and derivative works. However, this doc- 1582 ument itself may not be modified in any way, such as by removing the 1583 copyright notice or references to the Internet Society or other 1584 Internet organizations, except as needed for the purpose of develop- 1585 ing Internet standards in which case the procedures for copyrights 1586 defined in the Internet Standards process must be followed, or as 1587 required to translate it into languages other than English. 1589 The limited permissions granted above are perpetual and will not be 1590 revoked by the Internet Society or its successors or assigns. 1592 This document and the information contained herein is provided on an 1593 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1594 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1595 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1596 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MER- 1597 CHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1599 Acknowledgement 1601 Funding for the RFC Editor function is currently provided by the 1602 Internet Society. 1604 A. Appendix A -- Design Goals 1606 The design goals of the SASL C API are as follows: 1608 o To be simple and practical to use. 1610 o To provide related utility services in addition to core SASL func- 1611 tionality. 1613 o To be reasonably extensible. 1615 o To be suitable for use in a multi-threaded server or client. 1617 o To avoid dependancies on a specific memory allocation system, thread 1618 package or network model. 1620 o To be an independent service rather than a new layer. 1622 B. SASL API Index 1624 <>