[LON-CAPA-cvs] cvs: loncom /html/adm/help/tex Domain_Configuration_Network_SSL.tex doc/help domain.manual.texxml doc/loncapafiles loncapafiles.lpml

[raeburn]

raeburn		Thu Jul  9 21:04:17 2026 EDT

  Added files:                 
    /loncom/html/adm/help/tex	Domain_Configuration_Network_SSL.tex 

  Modified files:              
    /doc/loncapafiles	loncapafiles.lpml 
    /doc/help	domain.manual.texxml 
  Log:
  - Add documentation for LON-CAPA Network (SSL) to Domain Coordination manual.
  
  
Index: doc/loncapafiles/loncapafiles.lpml
diff -u doc/loncapafiles/loncapafiles.lpml:1.1090 doc/loncapafiles/loncapafiles.lpml:1.1091
--- doc/loncapafiles/loncapafiles.lpml:1.1090	Wed Jul  8 21:58:21 2026
+++ doc/loncapafiles/loncapafiles.lpml	Thu Jul  9 21:04:16 2026
@@ -2,7 +2,7 @@
  "http://lpml.sourceforge.net/DTD/lpml.dtd">
 <!-- loncapafiles.lpml -->
 
-<!-- $Id: loncapafiles.lpml,v 1.1090 2026/07/08 21:58:21 raeburn Exp $ -->
+<!-- $Id: loncapafiles.lpml,v 1.1091 2026/07/09 21:04:16 raeburn Exp $ -->
 
 <!--
 
@@ -3846,6 +3846,7 @@
 Domain_Configuration_Login_Page.tex;
 Domain_Configuration_LTI_Provider.tex;
 Domain_Configuration_LTI_Tools.tex;
+Domain_Configuration_Network_SSL.tex;
 Domain_Configuration_Passwords.tex;
 Domain_Configuration_Quotas.tex;
 Domain_Configuration_Request_Author.tex;
Index: doc/help/domain.manual.texxml
diff -u doc/help/domain.manual.texxml:1.30 doc/help/domain.manual.texxml:1.31
--- doc/help/domain.manual.texxml:1.30	Fri Mar  1 00:36:30 2024
+++ doc/help/domain.manual.texxml	Thu Jul  9 21:04:16 2026
@@ -88,6 +88,9 @@
     <subsection name="User Session Hosting/Offloading">
       <file name="Domain_Configuration_User_Sessions.tex" />
     </subsection>
+    <subsection name="LON-CAPA Network (SSL)">
+      <file name="Domain_Configuration_Network_SSL.tex" />
+    </subsection>
     <subsection name="Domain Trust Settings">
       <file name="Domain_Configuration_Trust.tex" />
     </subsection>

Index: loncom/html/adm/help/tex/Domain_Configuration_Network_SSL.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_Network_SSL.tex
\label{Domain_Configuration_Network_SSL}

Starting with LON-CAPA 2.12, information is displayed for each server in the
current LON-CAPA domain about the status of the SSL certificate which supports 
creation of an SSL tunnel used for exchange of a shared encryption key whenever 
a new TCP/IP connection is initiated between a LON-CAPA server's lonc and lond 
on a different LON-CAPA server.  The shared key is used to encrypt data on the 
lonc side before sending, and to decrypt data on the lond side upon receipt.

For each server information in the ``Certificate Status'' table is as follows.

\begin{itemize}

\item Status of Private Key
\item Status of corresponding Public ``Connections Certificate''
\item Status of LON-CAPA Replication and CA Certificates
\item Current status of Revocations List.

\end{itemize} 

The same private Key is also used to generate a client SSL certificate (the 
``Replication Certificate'') sent with any web request to port 443 on another
LON-CAPA server when requesting URLs which are only accessible to other servers
in the LON-CAPA network. Information available for the client certificate for 
each of the domain's servers is listed in the ``Replication Certificate'' row in
the ``Certificate Status'' table. 

For all servers in a LON-CAPA domain, options can be configured for the following:

\begin{itemize}

\item Use of an SSL tunnel for key exchange when lonc connects \textbf{to} another server's lond.
\item Use of an SSL tunnel for key exchange when lond accepts a connection \textbf{from} another server's lonc.

\end{itemize}

In both cases, options available are:

\begin{itemize}

\item Not used
\item Optional (used if available)
\item Required

\end{itemize}

Different rules can be set based on the remote server's affiliation, which will be
one of:

\begin{itemize}

\item Same domain
\item Different domain, but same ``internet domain''
\item Different domain and different ``internet domain''

\end{itemize}

The ``internet domain'' is the last item in each server's colon-separated entry 
in /home/httpd/lonTabs/dns_hosts.tab. Typically servers belonging to different
domains, but sharing the same ``internet domain'', are LON-CAPA domains housed
at the same institution.  For example, the ``internet domain'' of msu.edu is
shared by three domains: msu, msudemo, and msuk12.

Verification of the client SSL certificate sent by a remote LON-CAPA server, i.e., 
that server's ``Replication Certificate'') when a URL for which web requests are
only permitted from other LON-CAPA servers, e.g., replication of published content,
can be set to a default of either ``required'', or ``not required''.

If a verified client certificate is required by default, specific institution(s), 
i.e, ``internet domain(s)'' can be exempt.

Similarly, if a verified client certificate is not required by default, specific 
institution(s) can be excluded from that rule, in which case the certificate
will be required for them.

Creation of the Private key and each Certificate Signing Request (CSR) for a 
server's ``Connections Certificate'' and ``Replication Certificate'' occur when 
/UPDATE is run to install or update LON-CAPA.  There is also a perl script:
/home/httpd/lonCerts/manage_ssl_certs.pl which can be run (by root) to achieve
the same.

In both cases the CSRs are sent to certificate at loncapa.org for signing by the
LON-CAPA Certificate Authority (CA).  The CA will end a reply email, which contains
instructions and also the signed Connections Certificate, signed Replication Certificate,
and the LON-CAPA CA Certificate.

Once the three certificates are installed alongside the Private Key in /home/httpd/lonCerts,
they will be used as follows:

\begin{itemize}

\item When establishing a connection to another LON-CAPA server

-- If that server has a signed Connections Certificate installed, and both ends of the 
connection are configured to use an SSL tunnel for key exchange.

\item When requesting replication of content from another LON-CAPA server.

-- If the other server is running LON-CAPA 2.12.0 or newer, and the server belongs
to a different institution, and if the domain configuration for the remote server's 
domain requires the requester to provide a client certificate signed by the LON-CAPA CA.

\end{itemize}