Bug 1773234 - Added security and networking component drawing to FSD. Also updated the necko page. r=necko-reviewers,djackson,kershaw,manuel

Differential Revision: https://phabricator.services.mozilla.com/D179144

netwerk/docs/index.md

@@ -0,0 +1,45 @@
+# Networking
+
+The Necko (aka Networking) component is Gecko's implementation of the web's networking protocols.
+Most of the component's source lives in `netwerk` directory and this document's source can be found in `netwerk/docs`.
+This page mostly just points to helpful resources for contributing to and understanding Necko.
+More details can be found on [Necko's wiki](https://wiki.mozilla.org/Networking).
+The team can be reached:
+* on Matrix: [#necko:mozilla.org](https://chat.mozilla.org/#/room/#necko:mozilla.org)
+* by email: necko@mozilla.com
+* or by submitting a `Core::Networking` bug on [bugzilla.mozilla.org](https://bugzilla.mozilla.org/enter_bug.cgi?product=Core&component=Networking)
+
+## Contributing to Necko
+```{toctree}
+:maxdepth: 1
+http/logging
+submitting_networking_bugs.md
+```
+
+## Team resources
+```{toctree}
+:maxdepth: 1
+new_to_necko_resources
+neqo_triage_guideline.md
+```
+
+## Testing
+```{toctree}
+:maxdepth: 1
+network_test_guidelines.md
+http_server_for_testing
+```
+
+## Component/Feature details
+```{toctree}
+:maxdepth: 1
+http/lifecycle
+sec-necko-components.md
+cache2/doc
+http/http3.md
+dns/dns-over-https-trr
+url_parsers.md
+webtransport/webtransport
+captive_portals.md
+early_hints.md
+```

netwerk/docs/index.rst

@@ -1,25 +0,0 @@
-Networking
-==========
-
-These linked pages contain design documents for the Networking stack implementation in Gecko. They live in-tree under the 'netwerk/docs' directory.
-
-There is also documentation for the `HTTP server we use for unit tests`_.
-
-.. toctree::
-   :maxdepth: 1
-
-   cache2/doc
-   http/lifecycle
-   http/logging
-   http/http3.md
-   dns/dns-over-https-trr
-   submitting_networking_bugs.md
-   new_to_necko_resources
-   network_test_guidelines.md
-   url_parsers.md
-   webtransport/webtransport
-   captive_portals.md
-   early_hints.md
-   neqo_triage_guideline.md
-
-.. _HTTP server we use for unit tests: http_server_for_testing.html

netwerk/docs/sec-necko-components.md

@@ -0,0 +1,77 @@
+# Security and Networking Components
+
+This diagram models a high-level call flow upon performing an asyncOpen on an nsHttpChannel down into the NSS layer for a typical resource load.
+
+## Necko
+1. The LoadInfo, which contains [security related info](https://searchfox.org/mozilla-central/rev/27e4816536c891d85d63695025f2549fd7976392/netwerk/base/LoadInfo.h#284-294),
+ is passed to the channel (nsHttpChannel) on the parent process.
+2. The channel creates a transaction and the nsHttpConnectionMgr on the socket thread is signalled to handle the transaction.
+3. The transaction is then picked up on the socket thread and "dispatched" to a new or existing ConnectionEntry that is hashed by it's ConnectionInfo.
+4. The underlying connection, nsHttpConnection for Http/1.1 and Http/2 and HttpConnectionUDP for Http/3, will call into NSS for security functionality.
+
+## NSS
+Necko interacts with NSS through two distinct interfaces.
+ Primarily, most access flows via PSM which handles the configuration of TLS sockets, client certificate selection and server certificate verification.
+ However, Neqo (Mozilla's QUIC library) also relies directly on the TLS implementation inside NSS and uses it as an interface directly.
+
+NSS's internal structure is fairly convoluted, but there are five main areas relevant for Necko. Starting from the lowest level:
+1. [blapi.h](https://searchfox.org/mozilla-central/source/security/nss/lib/freebl/blapi.h) - exposes the wrappers for each cryptographic primitive supported by NSS and dispatches them to platform specific implementations.
+2. [pkcs11c.c](https://searchfox.org/mozilla-central/source/security/nss/lib/softoken/pkcs11c.c) - This wraps those underlying crypto primitives to provide a PKCS11 interface as a single module.
+3. [pk11pub.h](https://searchfox.org/mozilla-central/source/security/nss/lib/pk11wrap/pk11pub.h) - This wraps any module providing a PKCS11 interface and exposes high level cryptographic operations. It is widely used across Firefox.
+4. [ssl.h](https://searchfox.org/mozilla-central/source/security/nss/lib/ssl/ssl.h) and [sslexp.h](https://searchfox.org/mozilla-central/source/security/nss/lib/ssl/sslexp.h) expose our TLS interface for use in Necko's TLS and Neqo's QUIC connections.
+5. [cert.h](https://searchfox.org/mozilla-central/source/security/nss/lib/certdb/cert.h) exposes the certificate database functionality. [pkix.h](https://searchfox.org/mozilla-central/source/security/nss/lib/mozpkix/include/pkix/pkix.h) exposes the MozPkix certificate chain validation functions.
+
+
+```{mermaid}
+classDiagram
+
+class LoadInfo{
+    +Principal(s) (loading, triggering, toInherit)
+    +Context
+}
+
+nsHttpChannel --> nsHttpTransaction
+nsHttpTransaction --> nsHttpConnectionMgr
+nsHttpConnectionMgr --> ConnectionEntry : Via ConnectionInfo hash
+ConnectionEntry --> HttpConnectionBase
+
+HttpConnectionBase <-- nsHttpConnection : Is A
+HttpConnectionBase <-- HttpConnectionUDP : Is A
+
+nsHttpConnection --> nsSocketTransport2
+nsSocketTransport2 --> PSM
+PSM --> NSPR
+PSM --> `Off Main Thread CertVerifier`
+Neqo --> `Off Main Thread CertVerifier`
+
+%% for Http/3
+HttpConnectionUDP --> Http3Session : Http/3
+HttpConnectionUDP --> nsUDPSocket : Http/3
+nsUDPSocket --> NSPR : Http/3
+Http3Session --> Neqo : Http/3
+
+%% security TCP stack
+PSM --> TLS
+`Off Main Thread CertVerifier` --> Pcks11
+TLS --> Pcks11
+Pcks11 --> Blapi
+Blapi --> `Crypto Primitives`
+`Crypto Primitives` --> `Platform-Specific Crypto Implementations`
+
+%% transport security info
+PSM -- Transport Security Info
+Transport Security Info --> nsHttpChannel
+
+%% security UDP stack
+Neqo --> TLS
+`Off Main Thread CertVerifier`--> CertDB
+CertDB --> Builtins
+
+
+%% classes
+
+nsHttpChannel o-- LoadInfo
+nsHttpChannel o-- StreamListener
+nsHttpConnectionMgr o-- ConnectionEntry : Many
+
+```