[LON-CAPA-cvs] cvs: loncom / CrGenerate.pl
foxr
lon-capa-cvs@mail.lon-capa.org
Fri, 02 Jul 2004 10:19:59 -0000
foxr Fri Jul 2 06:19:59 2004 EDT
Modified files:
/loncom CrGenerate.pl
Log:
Write pod documentation on this script. Presumably this would be manified.
The installation script writers will need to decide if this script should
be automatically invoked at install time or added to the installation
documentaiton. Note that it is not necessary to run this script at update
time unless the user is upgrading from insecure to secure. So we probably
want to just ship the script and document it for updaters.
Index: loncom/CrGenerate.pl
diff -u loncom/CrGenerate.pl:1.6 loncom/CrGenerate.pl:1.7
--- loncom/CrGenerate.pl:1.6 Fri Jul 2 05:43:40 2004
+++ loncom/CrGenerate.pl Fri Jul 2 06:19:59 2004
@@ -2,7 +2,7 @@
# The LearningOnline Network
# CrGenerate - Generate a loncapa certificate request.
#
-# $Id: CrGenerate.pl,v 1.6 2004/07/02 09:43:40 foxr Exp $
+# $Id: CrGenerate.pl,v 1.7 2004/07/02 10:19:59 foxr Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -71,7 +71,7 @@
# Debug/log support:
#
-my $DEBUG = 1; # 1 for on, 0 for off.
+my $DEBUG = 0; # 1 for on, 0 for off.
# Send debugging to stderr.
# Parameters:
@@ -440,3 +440,124 @@
Cleanup; # Cleanup temp files created.
Debug("Done");
+
+#---------------------- POD documentatio --------------------
+
+=head1 NAME
+
+ CrGenerate - Generate a loncapa certificate request.
+
+=head1 SYNOPSIS
+
+Usage: B<CrGenerate>
+
+This should probably be run automatically at system
+installation time. Root must run this as write access is
+required to /home/httpd.
+
+This is a command line script that:
+
+ - Generates a hostkey and certificate request.
+ - Installs the protected/decoded host key where
+ secure lond/lonc can find it.
+ - Emails the certificate request to the loncapa certificate
+ manager.
+
+In due course if all is legitimate, the loncapa certificate
+manager will email a certificate installation script to
+the local loncapa system administrator.
+
+=head1 DESCRIPTION
+
+Using the default openssl configuration file, a certificate
+request and local hostkey are created in the current working
+directory. The local host key is decoded and installed in the
+loncapa certificate directory. This allows the secure versions
+of lonc and lond to locate them when attempting to form
+external connections. The key file is given mode
+0400 to secure it from prying eyes.
+
+The certificate request in PEM form is attached to an email that
+contains the textual equivalent of the certificate request
+and sent to the loncapa certificate manager. All temporary
+files (certificate request, keys etc.) are removed from the
+current working directory.
+
+It is recommended that the directory this script is run in have
+permission mask 0700 to ensure that there are no timing holes
+during which the decoded host key file can be stolen.
+
+During certificate generation, the user will receive several
+prompts. For the default LonCAPA openssl configuration,
+these prompts, and documentation and sample responses
+in angle brackets (<>) are shown below:
+
+ Country Name (2 letter code) [GB]: <your country e.g. US>
+ State or Province Name (full name) [Berkshire]: <State, province prefecture etc. e.g. Michigan>
+ Locality Name (eg, city) [Newbury]: <City township or municipality e.g. East Lansing>
+ Organization Name (eg, company) [My Company Ltd]: <corporate entity e.g. Michigan State University>
+ Organizational Unit Name (eg, section) []: <unit within Organization e.g. LITE lab>
+ Common Name (eg, your name or your server's host name) [] <server's hostname e.g. myhost.university.edu>
+ Email Address []: <Address to which the granted certificate should be sent e.g. me@university.edu>
+
+ Please enter the following 'extra' attributes
+ to be sent with your certificate request
+ A challenge password []: <leave this blank!!!!!>
+ An optional company name []: <Put whatever you want or leave blank>
+
+
+=head1 DEPENDENCIES
+
+ - MIME::Entity Used to create the email message.
+ - LONCAPA::Configuration Used to parse the loncapa configuration files.
+ - File::Copy Used to install the key file.
+ - /usr/lib/sendmail Properly configured sendmail, used to send the
+ certificate request email to the loncapa
+ certificate administrator.
+ - /etc/httpd/conf/* Loncapa configuration files read to locate
+ the certificate directory etc.
+
+=head1 FILES
+
+ The following temporary files are created in the cwd
+
+ hostkey.pem - PEM formatted version of the encrypted host key.
+ hostkey.dec - PEM formatted decrypted version of the host key.
+ request.pem - PEM formatted certificate request.
+ request.txt - Textual rendering of the certificate request.
+
+ The following permanent file is created:
+
+ $CertDir/$Keyfile - The installed decoded host key file. $CertDir
+ is defined by the Perl variable lonCertificateDirectory
+ in /etc/loncapa_apache.conf while $Keyfile is
+ defined by the perl variable lonnetPrivateKey in the
+ same configuration file.
+
+=head1 COPYRIGHT:
+
+ Copyright Michigan State University Board of Trustees
+
+ This file is part of the LearningOnline Network with CAPA (LON-CAPA).
+
+ LON-CAPA is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ LON-CAPA is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with LON-CAPA; if not, write to the Free Software
+ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+ /home/httpd/html/adm/gpl.txt
+
+
+=cut
+
+
+