1 2 idn wrapper - Client Side IDN Conversion Software for Windows 3 4 Copyright (c) 2000,2001,2002 Japan Network Information Center. 5 All rights reserved. 6 7 *** NOTICE ****************************************************** 8 If you have installed mDN Wrapper (former version of idn wrapper) 9 on your system, you should unwrap all the programs before 10 installing idn wrapper. 11 ***************************************************************** 12 13 141. Introduction 15 16 For supporting internationalized domain names, each client 17 application should convert domain names (their encodings) to that 18 DNS server accepts. This requires applications to handle 19 internationalized domain names in its core, and it is the vendor's 20 responsibility to make their programs IDN-compatible. 21 22 Although there are ongoing efforts in IETF to standardize IDN 23 framework (architecture, encoding etc.) and several RFCs are 24 expected to be published soon as the result, not many applications 25 support IDN to this date. 26 27 So, there are needs for some helper application which makes legacy 28 applications IDN-aware. `runidn' in idnkit is one of such 29 solutions for Unix-like operating systems, and this software, `idn 30 wrapper' is the one for Windows. 31 32 On windows, name resolving request is passed to WINSOCK DLL. idn 33 wrapper replaces WINSOCK DLL with the one that can handle IDN, 34 which makes legacy windows applications compatible with IDN. 35 362. Architecture 37 382.1. Wrapper DLL 39 40 Wrapper DLL resides between application and original DLL. It 41 intercept application's calls to original DLL, and preforms some 42 additional processing on those calls. 43 44 +------------+ Call +------------+ Call +------------+ 45 | |------->| |------->| | 46 |Application | |Wrapper DLL | |Original DLL| 47 | |<-------| |<-------| | 48 +------------+ Return +------------+ Return +------------+ 49 additional 50 processing 51 here 52 53 DLL call from apllication is passed to wrapper DLL. Wrapper DLL 54 then performs some additional processing on that call, and then 55 calls original DLL. Also, result from original DLL will once passed 56 to wrapper DLL and wrapper does additional process on that result, 57 and finally result will passed to the application. 58 59 idn wrapper provides wrapper DLLs for WINSOCK, 60 61 WSOCK32.DLL WINSOCK V1.1 62 WS2_32.DLL WINSOCK V2.0 63 64 to resolve multi-lingual domain names. 65 662.2. Wrapping APIs 67 68 idn wrapper performs additional processing on name resolving APIs in 69 WINSOCK, listed below. 70 71 both WINSOCK 1.1, WINSOCK 2.0 72 73 gethostbyaddr 74 gethostbyname 75 WSAAsyncGetHostByAddr 76 WSAAsyncGetHostByName 77 78 only in WINSOCK 2.0 79 80 getaddrinfo 81 freeaddrinfo 82 getnameinfo 83 WSALookupServiceBeginA 84 WSALookupServiceNextA 85 WSALookupServiceEnd 86 87 Some applications do not use these APIs to resolve domain names. 88 `nslookup' is one of those programs. `nslookup' builds and parse DNS 89 messages internally and does not use WINSOCK's name resolver APIs. 90 idn wrapper cannot make those programs IDN-aware. 91 92 NOTE: 93 WINSOCK 2.0 also contains WIDE-CHARACTER based name resolution 94 APIs, 95 96 WSALookupServiceBeginW 97 WSALookupServiceNextW 98 99 idn wrapper does not wrap these APIs. These APIs are used in 100 Microsoft's own internationalization framework. It is dangerous 101 to convert to another internationalization framework. 102 1032.3. Other APIs in WINSOCK 104 105 For other APIs in WINSOCK, idn wrapper does nothing, only calls 106 original DLL's entries. 107 108 idn wrapper copies original WINSOCK DLLs with renaming 109 as below, and forward requests to them. 110 111 wsock32.dll -> wsock32o.dll 112 ws2_32.dll -> ws2_32o.dll 113 114 Wrappper DLL will be installed with original DLL names. So after 115 installation of idn wrapper, WINSOCK DLLs should be 116 117 wsock32.dll idn wrapper for WINSOCK V1.1 118 ws2_32.dll idn wrapper for WINSOCK V2.0 119 wsock32o.dll Original WINSOCK V1.1 DLL 120 ws2_32o.dll Original WINSOCK V2.0 DLL 121 1222.4. Asynchronous API 123 124 Domain name conversion take place on 125 126 request to DNS 127 128 convert from local encoding to DNS compatible encoding 129 130 response from DNS 131 132 convert from DNS encoding to local encoding 133 134 For synchronous APIs, local to DNS conversion is done before calling 135 original API, and after return from original API, name should be 136 converted from DNS encoding to local encoding. 137 138 But WINSOCK having some asynchronous APIs, such as 139 140 WSAAsyncGetHostByAddr 141 WSAAsyncGetHostByName 142 143 In these APIs, completion is notified with windows message. To 144 perform DNS to local conversion, wrapper should hook target window 145 procedure to capture those completion messages. 146 147 So, if asynchronous API was called, idn wrapper set hook to target 148 window procedure (passed with API parameter). If hook found 149 notify message (also given with API parameter), then convert 150 resulting name (in DNS encoding) to local encoding. 151 1522.5. Installing Wrapper DLLs 153 154 WINSOCK DLLs are placed at Windows's system directory. To wrap 155 WINSOCK DLLs, one could do following sequence at system directory. 156 157 + Rename Original WINSOCK DLLs 158 159 ren wsock32.dll wsock32o.dll 160 ren ws2_32.dll ws2_32o.dll 161 162 + Install (copy in) Wrapper DLLs 163 164 copy somewhere\wsock32.dll wsock32.dll 165 copy somewhere\ws2_32.dll ws2_32.dll 166 copy another DLLs also 167 168 However, replacing DLLs in Window's system directory is very 169 dangerous: 170 171 a) If you re-install idn wrapper again, original WINSOCK DLLs 172 may be lost. 173 174 b) Some application or service pack will replace WINSOCK DLLs. It 175 may corrupt WINSOCK environment. 176 177 If these happen, at least networking does not work, and worse, 178 Windows never startup again. 179 180 So, idn wrapper usually does not wrap in the system directory, but wrap in 181 each indivisual application's directory. 182 183 In Windows, DLL will be searched in the following places: 184 185 Application's Load Directory 186 %SystemRoot%\System32 187 %SystemRoot% 188 Directories in PATH 189 190 and loaded & linked first found one. So if installed wrapper DLLs is 191 found on application's load directory, the application's call to 192 WINSOCK will wrapped. 193 194 But some applications or DLLs are binded to specific DLL, they do 195 not rely on above DLL's search path. For those applcaitons or DLLs, 196 idn wrapper (in standard installation) cannot wrap them. 197 198 NOTE: Netscape is one of those program. It cannot be wrapped if 199 installed to applications directory. Also WINSOCK DLLs are 200 also binded to related DLLs in system directory. On the 201 other hand, Internet Explore or Window Media Player relys on 202 standard DLL search path, and well wrapped with idn wrapper. 203 2042.6. At which point conversion applied 205 206 If windows supporting WINSOCK 2.0, there are DLLs one for 1.1 and 207 another for 2.0, and call to WINSOCK 1.1 will redirected to 2.0 DLL. 208 209 +------------+ Call +------------+ Call +------------+ 210 | |------->| |------->| | 211 |Application | |WINSOCK 1.1 | |WINSOCK 2.0 | 212 | |<-------| |<-------| | 213 +------------+ Return +------------+ Return +------------+ 214 215 In this case, calls to 1.1 and 2.0 are both passed to 2.0 DLL. So 216 conversion will done in WINSOCK 2.0 DLL side. 217 218 If windows only supports WINSOCK 1.1, there's 1.1 DLL only. 219 220 +------------+ Call +------------+ 221 | |------->| | 222 |Application | |WINSOCK 1.1 | 223 | |<-------| | 224 +------------+ Return +------------+ 225 226 In this case, conversion must done in 1.1 DLL. 227 228 If idn wrapper was installed on system directory, DLLs will work as 229 described above. But if wrapper was installed on application's 230 directory, call/return sequence changes. Original WINSOCK 1.1 DLL 231 in windows seems binded to specific WINSOCK 2.0 DLL, placed at 232 window's system diretory. So call from WINSOCK 1.1 to WINSOCK 2.0 233 will passed to original DLL (in system directory) and never passed 234 to wrapper DLL in application's directory. So in this case, both 235 1.1 and 2.0 DLLs should coonvert domain name encodings. 236 237 These DLL binding is not documented. It may be change on OS 238 versions or DLL versions. So, mDn wrapper determines place of 239 conversion on registry value. With this registry value, idn 240 wrappper absolb OS/DLL variations. 241 242 Registry values for idn wrapper will placed under 243 244 HKEY_LOCAL_MACHINE\SOFTWARE\JPNIC\IDN 245 HKEY_CURRENT_USER\SOFTWARE\JPNIC\IDN 246 247 Place of conversion is determined with registry value "Where", 248 249 Registry Value "Where" REG_DWORD 250 251 0 both on WINSOCK 1.1 and WINSOCK 2.0 252 1 if WINSOCK 2.0 exist, only in WINSOCK 2.0 253 otherwise, convert on WINSOCK 1.1 254 2 only in WINSOCK 1.1 255 3 only in WINSOCK 2.0 256 257 If you install idn wrapper into application's directory, use "0". 258 If you install idn wrapper into system directory, use "1". If there 259 are no "Where" value, idn wrapper uses "0" as default, it is suited 260 to installation into application's directory (default installation). 261 2622.7. Converting From/To 263 264 Wrapper DLL convert resolving domain name encoded with local code to 265 DNS server's encoding. Also, wrapper DLL convert resulting name ( 266 encoded with DNS's encoding) back to local encoding. 267 268 There are several proposals for DNS encodings to handle multi-lingual 269 domain names. Wrapper DLL should be configured to convert to one of 270 those encodings. This DNS side encoding will specified with 271 registry. When installing idn wrapper, this registry will set to 272 some (yet undefined) DNS encoding. 273 274 Registry values for idn wrapper will placed under 275 276 HKEY_LOCAL_MACHINE\SOFTWARE\JPNIC\IDN 277 HKEY_CURRENT_USER\SOFTWARE\JPNIC\IDN 278 279 DNS encoding name will given with registry value (REG_SZ) of "Encoding", 280 this name must be one of encoding names which 'libmdn' recognize. 281 282 Registry Value "Encoding" REG_SZ 283 284 Encoding name of DNS server accepts. 285 286 Local encodings (Windows Apllication Encodings) is generally 287 acquired from process's code page. 'iconv' library, used for idn 288 wrapper, generally accepts MS's codepage names. 289 290 Some windows apllication encode domain name with some specific multi- 291 lingual encoding. For example, if you configured IE to use UTF-8, 292 then domain names are encoded with UTF-8. UTF-8 is one of proposed 293 DNS encoding, but DNS server may expect another encoding. 294 295 For those cases, idn wrapper accept program specific encoding as 296 local encoding. These program specific local encoding should be 297 marked in registry. 298 299 Program specific registry setting will placed under 300 301 HKEY_LOCAL_MACHINE\SOFTWARE\JPNIC\IDN\PerProg 302 HKEY_CURRENT_USER\SOFTWARE\JPNIC\IDN\PerProg 303 304 using program name (executable file name) as key. For example, 305 setting specific to Internet Explore, it executable name is 306 "IEXPLORE", will plcaed at 307 308 HKEY_LOCAL_MACHINE\SOFTWARE\JPNIC\IDN\PerProg\IEXPLORE 309 310 Local encoding name will specified with registry value (REG_SZ) of 311 "Encoding". This name must be one of encoding names which ' 312 recognize.libmdn' 313 314 Registry Value "Encoding" REG_SZ 315 316 Encoding name of application program encodes, if it is not 317 system's default encoding. 318 3193. Setup and Configuration 320 321 idn wrapper wraps WINSOCK DLL by placing wrapper (fake) DLLs in 322 the application's directory. For the installation, idn wrapper 323 comes with a setup program and a configuration program. 324 325 NOTE: You can also install idn wrapper DLLs in the Windows 326 system directory. But this installation is very dangerous 327 and may cause severe problems in your system. 328 You should try it at your own risk. 329 3303.1. Setup Program 331 332 To install idn wrapper, run "setup.exe". Setup program will do: 333 334 Installing Files 335 336 Copy idn wrapper files (DLL, Program EXE, etc) into diretory 337 338 "\Program Files\JPNIC\idn wrapper" 339 340 This directory may be changed on setup sequence. 341 342 Setting registry entries 343 344 Setup program will create keys and values under registry: 345 346 "HKEY_LOCAL_MACHINES\Software\JPNIC\IDN" 347 348 InstallDir REG_SZ "<installation directory>" 349 Pathname of the idn wrapper's installation directory. 350 The installer makes copies of the original WINSOCK DLLs 351 in that directory, which is referenced by the idn wrapper's 352 fake DLLs. 353 354 ConfFile REG_SZ "<installation directory>\idn.conf" 355 Name of the idnkit's configuration file, which defines 356 various parameter regarding multilingual domain name 357 handling. See the contents of the file for details. 358 This value can be changed with the Configuration Program 359 or the registry editor. 360 361 LogFile REG_SZ "<installation directory>\idn_wrapper.log" 362 Name of the idn wrapper's log file. 363 This value can be changed with the Configuration Program 364 or the registry editor. 365 366 LogLevel DWORD -1 367 Logging level. Default is -1, which indicates no logging 368 is made. This value can be changed with the Configuration 369 Program or the registry editor. 370 371 PerProg KEY 372 373 Under this key, idn wrapper set program specific values. idn 374 wrapper uses program's executable name as key, and put 375 values under that key. 376 377 PerProg\<progname>\Where REG_DWORD Encoding Position 378 PerProg\>progname>\Encoding REG_SZ Local Encoding Name 379 380 Configuration program set local encpoding name. "Where" 381 value is usually not required in standard installation. If 382 you installed idn wrapper in system directory, chanage 383 "Where" values to fit your environment. 384 385 Creating ICON 386 387 Setup program will create program icon for idn wrapper's 388 configuration program, and put it into "Start Menu". You can 389 start configuration program with it. 390 3913.2. Configuration Program 392 393 Configuration program is a tool for wrap specific program, or unwrap 394 programs. If you start "Configuration Program", you'll get window 395 like this. 396 397 +---+-------------------------------------------------+---+---+---+ 398 | | idn wrapper - Configuration | _ | O | X | 399 +---+-------------------------------------------------+---+---+---+ 400 | idn wrapper Configuration Program version X.X | 401 +-----------------------------------------------------------------+ 402 | Wrapped Program +---------+ | 403 | +---------------------------------------------+---+ | Wrap.. | | 404 | | | A | +---------+ | 405 | | +---+ +---------+ | 406 | | | | | Unwrap..| | 407 | | | | +---------+ | 408 | | | | +---------+ | 409 | | | | |UnwrapAll| | 410 | | | | +---------+ | 411 | | | | +---------+ | 412 | | | | |RewrapAll| | 413 | | | | +---------+ | 414 | | | | +---------+ | 415 | | | | | Log.. | | 416 | | | | +---------+ | 417 | | | | +---------+ | 418 | | +---+ |Advanced.| | 419 | | | V | +---------+ | 420 | +---+-------------------------------------+---+---+ +---------+ | 421 | | < | | > | | Exit | | 422 | +---+-------------------------------------+---+ +---------+ | 423 +-----------------------------------------------------------------+ 424 425 Listbox contains list of current wrapped programs. Initially it is 426 empty. 427 428 To wrap a program, press button "wrap". You'll get following dialog. 429 430 +---+-------------------------------------------------+---+---+---+ 431 | | idn wrapper - Wrap Executable | _ | O | X | 432 +---+-------------------------------------------------+---+---+---+ 433 | +----------------------------------------+ +--------+ | 434 | Program: | | |Browse..| | 435 | +----------------------------------------+ +--------+ | 436 | +----------+ | 437 | Encoding: | | o Default o UTF-8 | 438 | +----------+ | 439 | [] Force local DLL reference | 440 +-----------------------------------------------------------------+ 441 | +--------+ +--------+ | 442 | | Wrap | | Cancel | | 443 | +--------+ +--------+ | 444 +-----------------------------------------------------------------+ 445 446 First, enter program (executable name with full path) or browse 447 wrapping exectable from file browser. Then set local encoding of 448 that program. Usually use "Default" as local encoding. If target 449 program uses internationalized encoding, then specify "UFT-8". 450 451 The "Force local DLL reference" button controls the DLL search 452 order of the program to be wrapped (Windows95 does not have this 453 capability, hence this button does not appear). If it is checked, 454 DLLs in the local directory (the directory which the executable 455 file is in) are always preferred, even if the executable specifies 456 otherwise. If you have problem with wrapping, checking this 457 button may solve the problem, but it is also possible that it 458 causes other problem. 459 460 Finally, put "wrap" button to wrap specified program with given 461 encoding. Wrapped program will be listed in listbox of the first 462 window. 463 464 When you install a new version of idn wrapper, you have to re-wrap 465 your programs in order to update DLLs used for wrapping. "Rewrap 466 all" button is provided for this purpose. Just press the button, 467 and all the currently wrapped programs will be re-wrapped. 468 469 To unwrap a program, press button "unwrap". You'll get following 470 confirmating dialog. 471 472 +---+-------------------------------------------------+---+---+---+ 473 | | idn wrapper - Unwrap Executable | _ | O | X | 474 +---+-------------------------------------------------+---+---+---+ 475 | +---------------------------------------------------+ | 476 | Program: | | | 477 | +---------------------------------------------------+ | 478 +-----------------------------------------------------------------+ 479 | +--------+ +--------+ | 480 | | Unwrap | | Cancel | | 481 | +--------+ +--------+ | 482 +-----------------------------------------------------------------+ 483 484 If you unwrap a program, the program will be vanished from listbox 485 of the first window. 486 487 Also "Unwrap all" button is provided to unwrap all the programs 488 that are currently wrapped. 489 490 To configure logging, press button "log". You'll get the following 491 dialog. 492 493 +---+-------------------------------------------------+---+---+---+ 494 | | idn wrapper - Log Configuration | _ | O | X | 495 +---+-------------------------------------------------+---+---+---+ 496 | Log Level: o None o Fatal o Error o Warning o Info o Trace | 497 | | 498 | +------------------------------------+ +---------+ | 499 | Log File:| | | Browse..| | 500 | +------------------------------------+ +---------+ | 501 | +------+ +--------+ | 502 |Log Operation: | View | | Delete | | 503 | +------+ +--------+ | 504 +-----------------------------------------------------------------+ 505 | +--------+ +--------+ | 506 | | OK | | Cancel | | 507 | +--------+ +--------+ | 508 +-----------------------------------------------------------------+ 509 510 Logging level can be selected from the followings. 511 None no logging at all 512 Fatal only records fatal errors 513 Error also records non-fatal errors 514 Warning also records warning mssages 515 Info also records informational messages 516 Trace also records trace information 517 Note that these levels are for log output from IDN library (idnkit.dll). 518 idn wrapper itself supports only off (None) and on (the rest). 519 520 Pathname of the log file can also be specified with this dialog. 521 522 You can view the current log file contents by pressing "View" button, 523 or delete it by "Delete" button. 524 525 Note that log level and log file configuration doesn't affect already 526 running processes. 527 528 Press "advanced" button to invoke the advanced configuration dialog. 529 This dialog is for advanced users and enables customization for 530 some basic parameters which normal users need not change, since 531 appropriate defaults are provided. 532 533 +---+-------------------------------------------------+---+---+---+ 534 | | idn wrapper - Advanced Configuration | _ | O | X | 535 +---+-------------------------------------------------+---+---+---+ 536 | IDN Wrapping Mode | 537 | o Wrap both WINSOCK 1.1 and WINSOCK 2.0 | 538 | o Wrap only WINSOCK 1.1 | 539 | o Wrap only WINSOCK 2.0 | 540 | o Wrap only WINSOCK 2.0 if it exists. | 541 | Otherwise wrap only WINSOCK 1.1 | 542 +-----------------------------------------------------------------+ 543 | IDN Configuration | 544 | +--------------------------------+ +----------+ | 545 | Config File: | | | Browse.. | | 546 | +--------------------------------+ +----------+ | 547 | +------+ | 548 | | Edit | | 549 | +------+ | 550 +-----------------------------------------------------------------+ 551 | +--------+ +--------+ | 552 | | OK | | Cancel | | 553 | +--------+ +--------+ | 554 +-----------------------------------------------------------------+ 555 556 With the dialog users can do the following configuration. 557 558 Wrapping Mode 559 Customize wrapping mode. Normally the default item should be 560 appropriate. Changing it to other item may help when you 561 have problems. 562 563 IDN Configuration 564 Set the configuration file for multilingual domain name handling. 565 By pressing "Edit" button, you can edit then contents of the file. 566 5674. Limitations 568 5694.1. DLL Versions 570 571 Wrapper DLL is tightly coupled with specific DLL version, because 572 it must export all the entries including un-documented ones. 573 If WINSOCK DLL version changed, idn wrapper may not work correctly. 574 575 Current idn wrapper is tested on 576 577 Win2000 (WINSOCK 1.1 + 2.0) 578 WinME (WINSOCK 1.1 + 2.0) 579 580 But there are no assuarance for future versions of Windows. 581 5824.2. DNS, WINS, LMHOSTS 583 584 There are three name resolving methods in windows, DNS, WINS and 585 LMHOSTS. Using idn wrapper, domain name conversion will performed 586 on all of thoses methods. It may cause some trouble if windows 587 using WINS or LMHOSTS. We recommend use DNS oly if you want to use 588 idn wrapper. 589 5904.3. Converting Names other than Domain Name 591 592 In WINSOCK 2.0, there are generic name resolution APIs are 593 introduced. 594 595 WSALookupServiceBeginA 596 WSALookupServiceNextA 597 WSALookupServiceEnd 598 599 They are use mainly domain name conversion now, but not limited to 600 resolving domain name. idn wrapper hooks this API and convert 601 given name anyway. This causes some trouble if conversion name is 602 not domain name. 603 6044.4. Applications don't use these APIa 605 606 Some applications don't use these APIs to resolving domain names. 607 For example, 'nslookup' issue DNS request locally. For these 608 applications, idn wrapper does not work. 609 6104.5. Applications bound to specific WINSOCK DLL 611 612 Some applications are bound to specific DLL, not relying on 613 standard DLL search path. Netscape Communicator seems to be one of 614 such programs. idn wrapper in standard installation cannot wrap 615 such programs. 616 617 If you want to wrap those programs, you may use installation into 618 system directory. But this installation is very dangerous, for 619 it is possible that your system cannot boot again. 620 6215. Registry Setting - Summary 622 6235.1. Priority of Setting 624 625 Settings of idn wrapper is placed on registry 626 627 Software\JPNIC\IDN 628 629 under HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER. idn wrapper first 630 read HKEY_LOCAL_MACHINE, and if HKEY_CURRENT_USER exist, overwrite 631 with this one. Usually set HKEY_LOCAL_MACHINE only. But if you 632 need per user setting, then set HKEY_CURRENT_USER. 633 634 Note that the configuration program reads/writes only 635 HKEY_LOCAL_MACHINE. 636 6375.2. Registry Key 638 639 There's common settings and per program settings. 640 641_Common Settings 642 643 Software\JPNIC\IDN\InstallDir Installation directory 644 Software\JPNIC\IDN\Where Where to convert encoding 645 0: both WINSOCK 1.1 and WINSOCK 2.0 646 1: if WINSOCK 2.0 exist, convert at 2.0 DLL 647 if WINSOCK 1.1 only, convert at 1.1 DLL 648 2: only in WINSOCK1.1 649 3: only in WINSOCK2.0 650 Software\JPNIC\IDN\ConfFile idnkit Configuration File 651 Software\JPNIC\IDN\LogFile Log File 652 Software\JPNIC\IDN\LogLevel Log Level 653 654_Per Program Settings 655 656 Converting position and program's local encoding may be set per 657 program bases. 658 659 Software\JPNIC\IDN\PerProg\<name>\Where 660 Software\JPNIC\IDN\PerProg\<name>\Encoding 661 662 If not specified, the following values are assumed. 663 664 Where 0 (both 1.1 DLL and 2.0 DLL) 665 Encoding [process's code page] 666