Document Heimdal's PKIX, kx509, bx509

This reverts commit 5c25450e50.

doc/heimdal.texi

@@ -22,19 +22,20 @@
 @ifinfo
 @dircategory Security
 @direntry
-* Heimdal: (heimdal).           The Kerberos 5 distribution from KTH
+* Heimdal: (heimdal).           The Kerberos 5 and PKIX distribution from KTH
 @end direntry
 @end ifinfo
 
 @c title page
 @titlepage
 @title Heimdal
-@subtitle Kerberos 5 from KTH
+@subtitle Kerberos 5 and PKIX from KTH
 @subtitle Edition @value{EDITION}, for version @value{VERSION}
 @subtitle 2008
 @author Johan Danielsson
 @author Love Hörnquist Åstrand
 @author Assar Westerlund
+@author et al
 
 @end titlepage
 
@@ -64,6 +65,10 @@ This manual for version @value{VERSION} of Heimdal.
 @menu
 * Introduction::                
 * What is Kerberos?::           
+* What is PKIX?::           
+* What is a Certification Authority (CA)?::           
+* What is kx509?::           
+* What is bx509?::           
 * Building and Installing::     
 * Setting up a realm::          
 * Applications::                

doc/hx509.texi

@@ -48,7 +48,7 @@
 
 @page
 @copyrightstart
-Copyright (c) 1994-2008 Kungliga Tekniska Högskolan
+Copyright (c) 1994-2019 Kungliga Tekniska Högskolan
 (Royal Institute of Technology, Stockholm, Sweden).
 All rights reserved.
 
@@ -187,7 +187,7 @@ This manual is for version @value{VERSION} of hx509.
 
 @menu
 * Introduction::
-* What is X.509 ?::
+* What are X.509 and PKIX ?::
 * Setting up a CA::
 * CMS signing and encryption::
 * Certificate matching::
@@ -230,13 +230,20 @@ Software PKCS 11 module
 @end detailmenu
 @end menu
 
-@node Introduction, What is X.509 ?, Top, Top
+@node Introduction, What are X.509 and PKIX ?, Top, Top
 @chapter Introduction
 
-The goals of a PKI infrastructure (as defined in 
+A Public Key Infrastructure (PKI) is an authentication mechanism based on
-<a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280</a>) is to meet 
+entities having certified cryptographic public keys and corresponding private
-@emph{the needs of deterministic, automated identification, authentication, access control, and authorization}.
+(secret) keys.
 
+The ITU-T PKI specifications are designated "x.509", while the IETF PKI
+specifications (PKIX) are specified by a number of Internet RFCs and are based
+on x.509.
+
+The goals of a PKI (as stated in 
+<a href="http://www.ietf.org/rfc/rfc5280.txt">RFC 5280</a>) is to meet 
+@emph{the needs of deterministic, automated identification, authentication, access control, and authorization}.
 
 The administrator should be aware of certain terminologies as explained by the aforementioned
 RFC before attemping to put in place a PKI infrastructure. Briefly, these are: 
@@ -246,6 +253,9 @@ RFC before attemping to put in place a PKI infrastructure. Briefly, these are:
 Certificate Authority
 @item RA
 Registration Authority, i.e., an optional system to which a CA delegates certain management functions.
+@item Certificate
+A binary document that names an entity and its public key and which is signed
+by an issuing CA.
 @item CRL Issuer
 An optional system to which a CA delegates the publication of certificate revocation lists.
 @item Repository
@@ -253,7 +263,7 @@ A system or collection of distributed systems that stores certificates and CRLs
 and serves as a means of distributing these certificates and CRLs to end entities
 @end itemize
 
-hx509 (Heimdal x509 support) is a near complete X.509 stack that can
+hx509 (Heimdal x509 support) is a near complete X.509/PKIX stack that can
 handle CMS messages (crypto system used in S/MIME and Kerberos PK-INIT)
 and basic certificate processing tasks, path construction, path
 validation, OCSP and CRL validation, PKCS10 message construction, CMS
@@ -263,10 +273,13 @@ signed), and CMS EnvelopedData (certificate encrypted).
 hx509 can use PKCS11 tokens, PKCS12 files, PEM files, and/or DER encoded
 files.
 
-@node What is X.509 ?, Setting up a CA, Introduction, Top
+hx509 consists of a library (libhx509) and a command-line utility (hxtool), as
-@chapter What is X.509, PKIX, PKCS7 and CMS ? 
+well as a RESTful, HTTPS-based service that implements an online CA.
 
-X.509 was created by CCITT (later ITU) for the X.500 directory
+@node What are X.509 and PKIX ?, Setting up a CA, Introduction, Top
+@chapter What are X.509 and PKIX, PKIX, PKCS7 and CMS ? 
+
+X.509 was created by CCITT (later ITU-T) for the X.500 directory
 service. Today, X.509 discussions and implementations commonly reference
 the IETF's PKIX Certificate and CRL Profile of the X.509 v3 certificate
 standard, as specified in RFC 3280.
@@ -348,7 +361,7 @@ The process starts by looking at the issuing CA of the certificate, by
 Name or Key Identifier, and tries to find that certificate while at the
 same time evaluting any policies in-place.
 
-@node Setting up a CA, Creating a CA certificate, What is X.509 ?, Top
+@node Setting up a CA, Creating a CA certificate, What are X.509 and PKIX ?, Top
 @chapter Setting up a CA
 
 Do not let information overload scare you off! If you are simply testing

doc/install.texi

@@ -1,4 +1,4 @@
-@node Building and Installing, Setting up a realm, What is Kerberos?, Top
+@node Building and Installing, Setting up a realm,  What is bx509?, Top
 @comment  node-name,  next,  previous,  up
 @chapter Building and Installing
 

doc/whatis.texi

@@ -1,6 +1,6 @@
 @c $Id$
 
-@node What is Kerberos?, Building and Installing, Introduction, Top
+@node What is Kerberos?, What is PKIX?, Introduction, Top
 @chapter What is Kerberos?
 
 @quotation
@@ -162,3 +162,53 @@ from 1988.
 
 These documents can be found on our web-page at
 @url{http://www.pdc.kth.se/kth-krb/}.
+
+@node What is PKIX?, What is a Certification Authority (CA)?, What is Kerberos?, Top
+@chapter What is PKIX?
+
+PKIX is the set of Internet standards for Public Key Infrastructure (PKI),
+based on the ITU-T's x.509 standads.  PKI is an authentication mechanism based
+on public keys (the 'PK' in 'PKI').
+
+In PKIX we have public keys "certified" by certification authorities (CAs).  A
+"relying party" is software that validates an entity's certificate and, if
+valid, trusts the certified public key to "speak for" the entity identified by
+the certificate.
+
+In a PKI every entity has one (or more) certified public/private key pairs.
+
+@node What is a Certification Authority (CA)?, What is kx509?, What is PKIX?, Top
+@chapter What is a Certification Authority (CA)?
+
+A Certification Authority (CA) is an entity in a PKI that issues certificates
+to other entities -- a CA certifies that a public key speaks for a particular,
+named entity.
+
+There are two types of CAs: off-line and online.  Typically PKI hierarchies are
+organized such that the most security-critical private keys are only used by
+off-line CAs to certify the less security-critical public keys of online CAs.
+
+Heimdal has support for off-line CAs using its Hx509 library and hxtool
+command.
+
+Heimdal also has an online CA with a RESTful, HTTPS-based protocol.
+
+@node What is kx509?, What is bx509?, What is a Certification Authority (CA)?, Top
+@chapter What is kx509?
+
+kx509 is a kerberized certification authority (CA).  Heimdal implements this
+protocol in its KDC.  The protocol is specified by <a
+href="http://www.ietf.org/rfc/rfc6717.txt">RFC 6717</a>, though Heimdal has
+implemented a number of extensions as well.  A client is implemented by the
+heimtools command's kx509 sub-command.
+
+@node What is bx509?, Building and Installing, What is kx509?, Top
+@chapter What is kx509?
+
+bx509 is an online CA, like kx509, but the protocol is based on HTTPS.
+
+Heimdal's bx509d implementation of bx509 implements two authentication bridges:
+a "/bx509" end-point that allows clients to trade bearer tokens (including
+Negotiate/Kerberos) and CSRs for certificates, and a "/bnegotiate" end-point
+allowing clients to trade bearer tokens (including Negotiate/Kerberos) for
+Negotiate tokens to HTTP servers.