netwerk/docs/sec-necko-components.md

   1 # Security and Networking Components
   2
   3 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.
   4
   5 ## Necko
   6 1. The LoadInfo, which contains [security related info](https://searchfox.org/mozilla-central/rev/27e4816536c891d85d63695025f2549fd7976392/netwerk/base/LoadInfo.h#284-294),
   7  is passed to the channel (nsHttpChannel) on the parent process.
   8 2. The channel creates a transaction and the nsHttpConnectionMgr on the socket thread is signalled to handle the transaction.
   9 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.
  10 4. The underlying connection, nsHttpConnection for Http/1.1 and Http/2 and HttpConnectionUDP for Http/3, will call into NSS for security functionality.
  11
  12 ## NSS
  13 Necko interacts with NSS through two distinct interfaces.
  14  Primarily, most access flows via PSM which handles the configuration of TLS sockets, client certificate selection and server certificate verification.
  15  However, Neqo (Mozilla's QUIC library) also relies directly on the TLS implementation inside NSS and uses it as an interface directly.
  16
  17 NSS's internal structure is fairly convoluted, but there are five main areas relevant for Necko. Starting from the lowest level:
  18 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.
  19 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.
  20 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.
  21 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.
  22 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.
  23
  24
  25 ```{mermaid}
  26 classDiagram
  27
  28 class LoadInfo{
  29     +Principal(s) (loading, triggering, toInherit)
  30     +Context
  31 }
  32
  33 nsHttpChannel --> nsHttpTransaction
  34 nsHttpTransaction --> nsHttpConnectionMgr
  35 nsHttpConnectionMgr --> ConnectionEntry : Via ConnectionInfo hash
  36 ConnectionEntry --> HttpConnectionBase
  37
  38 HttpConnectionBase <-- nsHttpConnection : Is A
  39 HttpConnectionBase <-- HttpConnectionUDP : Is A
  40
  41 nsHttpConnection --> nsSocketTransport2
  42 nsSocketTransport2 --> PSM
  43 PSM --> NSPR
  44 PSM --> `Off Main Thread CertVerifier`
  45 Neqo --> `Off Main Thread CertVerifier`
  46
  47 %% for Http/3
  48 HttpConnectionUDP --> Http3Session : Http/3
  49 HttpConnectionUDP --> nsUDPSocket : Http/3
  50 nsUDPSocket --> NSPR : Http/3
  51 Http3Session --> Neqo : Http/3
  52
  53 %% security TCP stack
  54 PSM --> TLS
  55 `Off Main Thread CertVerifier` --> Pcks11
  56 TLS --> Pcks11
  57 Pcks11 --> Blapi
  58 Blapi --> `Crypto Primitives`
  59 `Crypto Primitives` --> `Platform-Specific Crypto Implementations`
  60
  61 %% transport security info
  62 PSM -- Transport Security Info
  63 Transport Security Info --> nsHttpChannel
  64
  65 %% security UDP stack
  66 Neqo --> TLS
  67 `Off Main Thread CertVerifier`--> CertDB
  68 CertDB --> Builtins
  69
  70
  71 %% classes
  72
  73 nsHttpChannel o-- LoadInfo
  74 nsHttpChannel o-- StreamListener
  75 nsHttpConnectionMgr o-- ConnectionEntry : Many
  76
  77 ```