Updated ...md (markdown)

...md.md

@@ -12,19 +12,21 @@ As stated earlier, the main goal is side by side Windows support in the portable
 
 Guidelines
 -----------
-To prevent any regressions in main and to enable easier review of the changes coming from win32-fork, there will be no "main" code moving or refactoring. There are multiple places where platform abstraction makes sense (auth, console to name a few), but this wont be addressed in the fork as it would lead to significant code churn. This will be done post integration once we have stable Windows supported version with significant test coverage living in main repo. Crypto support using Windows [CNG](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376210(v=vs.85).aspx) has been tested out in fork but will its changes will be reverted\undone as it needed reasonable modifications to "main" code. This means that the Windows supported version potentially available mid this year will rely on OpenSSL's crypto (exception is SSP for key-based authentication that will use CNG - more details later).
+To prevent any regressions in main and to enable easier review of the changes coming from win32-fork, there will be no "main" code moving or refactoring. There are multiple places where platform abstraction makes sense (auth, console to name a few), but this wont be addressed in the fork as it would lead to significant code churn. This will be done post integration once we have stable Windows supported version with significant test coverage living in main repo. Crypto support using Windows [CNG](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376210(v=vs.85).aspx) has been tested out in fork but since it needed reasonable modifications to "main" code,  relevant changes will be reverted\undone. This means that the Windows supported version potentially available mid this year will rely on OpenSSL's crypto (exception is SSP for key-based authentication that will use CNG - more details later).
 
 Design details
 -------------
-### Transport Layer - POSIX IO
+Here, we'll discuss the design choices aimed at keeping majority of code base common between Unix and Windows, deviating where deemed necessary.
-This layer of protocol implementation in OpenSSH consists of mainly IO, parsing and crypto code. The aim it keep this layer mostly common between Windows and Unix by implementing a POSIX IO wrapper on top of Win32 async File IO (parsing is common for both, crypto will remain common for this milestone). This wrapper strictly implements the POSIX IO needs of OpenSSH keeping the code differences in transport layer to a minimum. Note that the wrapper implements only the calls needed by OpenSSH (and not all defined in POSIX standard). Specifically, the wrapper implements
+
+### POSIX IO
+POSIX IO calls are a significant part of OpenSSH code. A POSIX IO wrapper will be implemented on top of Win32 async File IO. This wrapper strictly implements the POSIX IO needs of OpenSSH keeping the code differences, especially in the transport layer, to a minimum. Note that the wrapper implements only the calls needed by OpenSSH (and not all defined in POSIX standard). Specifically, the wrapper implements
 + IO calls creating file descriptors - open, creat, socket, accept, socketpair, pipe
 + operations on a single file descriptor - fd_set, FD_* macros, read, write, recv, send, fstat, fdopen, close, dup and dup2
 + operations on multiple file descriptors - select
 + signal semantics on these operations - ex. select (or any blocking IO call) returning EINTR
 + SIGABRT, SIGTERM, SIGCHLD, SIGINT, SIGPIPE and SIGALRM
 
-Brief design details of POSIX wrapper
+Design summary of POSIX wrapper
 + Single threaded (not thread safe based on current needs but can be made so if needed going forward). 
 + Maintains file descriptor table and its state. Table stores mapping between file descriptors (int) and associated Windows IO state (handle, buffers, async call state, etc). 
 + fd_set implemented as a bit array, lowest available file descriptors get allocated first.
@@ -35,7 +37,7 @@ Brief design details of POSIX wrapper
   - Timers
 + All underlying Win32 IO API calls are made asynchronous (non-blocking). Blocking semantics are implemented within the wrapper by an explicit "wait_for_any" for IO to complete.
 + Uses [APCs](https://msdn.microsoft.com/en-us/library/windows/desktop/ms681951(v=vs.85).aspx) wherever available and minimzing use of [events](https://msdn.microsoft.com/en-us/library/windows/desktop/ms682655(v=vs.85).aspx). This simplifies code and has performance benefits.
-+ Maintains internal buffers to accommodate an underlying fundamental difference between POSIX and Win32 IO APIs - IOReady Vs IOComplete (Ex for a Read operation, POSIX APIs signal when IO is ready - date will be subsequently, explicitly read, Win32 APIs signal when IO has completed - data is already copied to a user provided buffer. Though this may be perceived as a performance hit, a validation exercise did not show any major impact. It in fact proved beneficial in reducing kernel calls during "read"s (ex. reading a header, would fetch the entire packet in a single call). 
++ Maintains internal buffers to accommodate a fundamental underlying difference between POSIX and Win32 IO async models - IOReady Vs IOComplete (Ex for a Read operation, POSIX APIs signal when IO is ready - date will be subsequently explicitly read, Win32 APIs signal when IO has completed - data is already copied to a user provided buffer. Though this may be perceived as a performance hit, a validation exercise did not show any major impact. It in fact proved beneficial in reducing kernel calls during "read"s (ex. reading a header, would fetch the entire packet in a single call). 
 + Additional details on underlying Win32 calls used
 
 | POSIX IO call  |  Underlying Win32 IO call(s) | Additional details |
@@ -56,13 +58,22 @@ Brief design details of POSIX wrapper
 
 A fully functional prototype (for socket, file and pipe IO) of this wrapper is available [here](https://github.com/PowerShell/Win32-OpenSSH/tree/L2-Win32Posix-Prototype/contrib/win32/w32-posix-prototype/win32posix.)
 
+#### fork()
+There is no easy fork() equivalent in Windows. fork() is used in OpenSSH in multiple places, of those - 2 are worth mentioning 
++ Session isolation: Each accepted connection in sshd is handed off and processed in a forked child. This will be implemented in Windows using CreateProcess based custom logic - will need #def differentiated code between Unix and Windows
++ Privilege separation: Implemented by processing and parsing network data in forked and underprivileged child processes that communicate to privileged Monitor process through IPC. Monitor does the core crypto validation and authentication. Security model in Windows is going to be different, running the SSHD service itself in a low privileged mode. So, the whole Privilege separation relevant code will be #def'ed out into a separate feature that will be disabled in Windows.
+
 #### AF_UNIX domain sockets
 Unix domain sockets are used for IPC communication between processes on the same host. Apart from providing stream/datagram modes, they also support a secure way to transmit ancillary data (like file descriptors). The only place ancillary data is used in OpenSSH is in "ProxyUseFDPass" feature where a proxy command is issued by ssh client to create a connected socket, and its FD is transmitted back over IPC. This feature will be disabled on Windows. The rest of the places AF_UNIX sockets are used:
-+ ControlMaster - used to multiplex multiple sessions over a single SSH connection. A secure Windows pipe can be used for this purpose.
++ ControlMaster - used to multiplex multiple sessions over a single SSH connection. 
 + SSHAgent - used to managed store keys and crypto validation based on those. Current plan is to replace its client side usage with Windows Credential manager. Server side plan is TBD. 
 + Local Socket Forwarding - This is forwarding traffic to AF_UNIX sockets and this feature is not applicable in Windows
-+ SSHD rexec - TBD
++ SSHD rexec - Not applicable for Windows. SSHD will be implemented as Windows service, that can be configured for auto restart.
-+ SSHD from inetd - TBD
++ SSHD from inetd - Not applicable for Windows. 
+AF_UNIX channel will be implemented using secure bidirectional named pipes in Windows. This does not support ancillary data but is sufficient for above listed features relevant in Windows. 
+
+#### Privilege Separation
+