Updated documentation to include examples of XML certificates.

8 files changed, 270 insertions, 8 deletions

diff --git a/doc/tex/Makefile.am b/doc/tex/Makefile.am
index 08e35a69ff..bfede16674 100644
--- a/doc/tex/Makefile.am
+++ b/doc/tex/Makefile.am
@@ -7,7 +7,7 @@ TEX_OBJECTS = gnutls.tex ../../lib/gnutls-api.tex serv1.tex ex1.tex ex2.tex ex3.
 	auth.tex ciphers.tex errors.tex layers.tex alert.tex record.tex \
 	funcs.tex examples.tex ex4.tex ../../libextra/gnutls-extra-api.tex \
 	memory.tex intro.tex openpgp.tex x509.tex howto.tex openssl.tex \
-	ex-rfc2818.tex
+	ex-rfc2818.tex appendix.tex x509cert.xml.tex pgpcert.xml.tex
 
 gnutls.html: $(TEX_OBJECTS)            
 	-latex2html gnutls.tex -no_navigation -split 0 \
diff --git a/doc/tex/appendix.tex b/doc/tex/appendix.tex
new file mode 100644
index 0000000000..c0257303e2
--- /dev/null
+++ b/doc/tex/appendix.tex
@@ -0,0 +1,17 @@
+\appendix
+\chapter{Certificate to XML\index{Certificate to XML convertion} convertion functions}
+
+\label{xml}
+
+This appendix contains some example output of the XML convertion
+functions:
+\begin{itemize}
+\item \printfunc{gnutls_x509_certificate_to_xml}{gnutls\_x509\_certificate\_to\_xml}
+\item \printfunc{gnutls_openpgp_key_to_xml}{gnutls\_openpgp\_key\_to\_xml}
+\end{itemize}
+
+\section{An X.509 certificate}
+\input{x509cert.xml}
+
+\section{An OpenPGP key}
+\input{pgpcert.xml}
diff --git a/doc/tex/gnutls.tex b/doc/tex/gnutls.tex
index 797c251e4f..0a4863930f 100644
--- a/doc/tex/gnutls.tex
+++ b/doc/tex/gnutls.tex
@@ -50,7 +50,9 @@
 
 \input{funcs}
 
-\input{fdl.tex}
+\input{fdl}
+
+\input{appendix}
 
 \printindex
 
diff --git a/doc/tex/howto.tex b/doc/tex/howto.tex
index 6e7221b4d2..79224811d9 100644
--- a/doc/tex/howto.tex
+++ b/doc/tex/howto.tex
@@ -18,7 +18,7 @@ with this method is a denial of service one. The most famous
 example of this method is the famous ``HTTP over TLS'' or HTTPS\footnote{RFC2818} 
 protocol.
 \par
-Despite it's wide use, this method is as good as it seems.
+Despite it's wide use, this method is not as good as it seems.
 This approach starts the \tls{} Handshake procedure just after the
 client connects on the --so called-- secure port. 
 That way the \tls{} protocol does not know anything
@@ -35,7 +35,7 @@ the available privileged ports, this approach was soon obsoleted.
 
 
 \section{A different approach}
-Later application protocols\footnote{See LDAP, IMAP etc.}
+Other application protocols\footnote{See LDAP, IMAP etc.}
 use a different approach to enable the secure layer.
 They use something called the ``TLS upgrade'' method. This method
 is quite tricky but it is more flexible. The idea is to extend
diff --git a/doc/tex/macros.tex b/doc/tex/macros.tex
index adecaa79b7..58326008e0 100644
--- a/doc/tex/macros.tex
+++ b/doc/tex/macros.tex
@@ -10,6 +10,6 @@
 
 % accepts section name, function name
 \newcommand{\printfunc}[2]{%
-	\hyperref{#2}{#2()  (see section }{ p. \pageref{#1})}{#1}
+	\hyperref{#2}{#2()  (see section }{ p.\pageref{#1})}{#1}
 }
 
diff --git a/doc/tex/pgpcert.xml.tex b/doc/tex/pgpcert.xml.tex
new file mode 100644
index 0000000000..fe66e35e67
--- /dev/null
+++ b/doc/tex/pgpcert.xml.tex
@@ -0,0 +1,56 @@
+\begin{verbatim}
+
+<?xml version="1.0"?>
+<OPENPGPKEY>
+  <MAINKEY>
+    <KEYID>BD572CDCCCC07C3</KEYID>
+    <FINGERPRINT>BE615E88D6CFF27225B8A2E7BD572CDCCCC07C35</FINGERPRINT>
+    <PKALGO>DSA</PKALGO>
+    <KEYLEN>1024</KEYLEN>
+    <CREATED>1011533164</CREATED>
+    <REVOKED>0</REVOKED>
+    <KEY ENCODING="HEX"/>
+    <DSA-P>0400E72E76B62EEFA9A3BD594093292418050C02D7029D6CA2066EFC34C86038627C643EB1A652A7AF1D37CF46FC505AC1E0C699B37895B4BCB3E53541FFDA4766D6168C2B8AAFD6AB22466D06D18034D5DAC698E6993BA5B350FF822E1CD8702A75114E8B73A6B09CB3B93CE44DBB516C9BB5F95BB666188602A0A1447236C0658F</DSA-P>
+    <DSA-Q>00A08F5B5E78D85F792CC2072F9474645726FB4D9373</DSA-Q>
+    <DSA-G>03FE3578D689D6606E9118E9F9A7042B963CF23F3D8F1377A273C0F0974DBF44B3CABCBE14DD64412555863E39A9C627662D77AC36662AE449792C3262D3F12E9832A7565309D67BA0AE4DF25F5EDA0937056AD5BE89F4069EBD7EC76CE432441DF5D52FFFD06D39E5F61E36947B698A77CB62AB81E4A4122BF9050671D9946C865E</DSA-G>
+    <DSA-Y>0400D061437A964DDE318818C2B24DE008E60096B60DB8A684B85A838D119FC930311889AD57A3B927F448F84EB253C623EDA73B42FF78BCE63A6A531D75A64CE8540513808E9F5B10CE075D3417B801164918B131D3544C8765A8ECB9971F61A09FC73D509806106B5977D211CB0E1D04D0ED96BCE89BAE8F73D800B052139CBF8D</DSA-Y>
+  </MAINKEY>
+  <USERID>
+    <NAME>OpenCDK test key (Only intended for test purposes!)</NAME>
+    <EMAIL>opencdk@foo-bar.org</EMAIL>
+    <PRIMARY>0</PRIMARY>
+    <REVOKED>0</REVOKED>
+  </USERID>
+  <SIGNATURE>
+    <VERSION>4</VERSION>
+    <SIGCLASS>19</SIGCLASS>
+    <EXPIRED>0</EXPIRED>
+    <PKALGO>DSA</PKALGO>
+    <MDALGO>SHA1</MDALGO>
+    <CREATED>1011533164</CREATED>
+    <KEYID>BD572CDCCCC07C3</KEYID>
+  </SIGNATURE>
+  <SUBKEY>
+    <KEYID>FCB0CF3A5261E06</KEYID>
+    <FINGERPRINT>297B48ACC09C0FF683CA1ED1FCB0CF3A5261E067</FINGERPRINT>
+    <PKALGO>ELG</PKALGO>
+    <KEYLEN>1024</KEYLEN>
+    <CREATED>1011533167</CREATED>
+    <REVOKED>0</REVOKED>
+    <KEY ENCODING="HEX"/>
+    <ELG-P>0400E20156526069D067D24F4D71E6D38658E08BE3BF246C1ADCE08DB69CD8D459C1ED335738410798755AFDB79F1797CF022E70C7960F12CA6896D27CFD24A11CD316DDE1FBCC1EA615C5C31FEC656E467078C875FC509B1ECB99C8B56C2D875C50E2018B5B0FA378606EB6425A2533830F55FD21D649015615D49A1D09E9510F5F</ELG-P>
+    <ELG-G>000305</ELG-G>
+    <ELG-Y>0400D0BDADE40432758675C87D0730C360981467BAE1BEB6CC105A3C1F366BFDBEA12E378456513238B8AD414E52A2A9661D1DF1DB6BB5F33F6906166107556C813224330B30932DB7C8CC8225672D7AE24AF2469750E539B661EA6475D2E03CD8D3838DC4A8AC4AFD213536FE3E96EC9D0AEA65164B576E01B37A8DCA89F2B257D0</ELG-Y>
+  </SUBKEY>
+  <SIGNATURE>
+    <VERSION>4</VERSION>
+    <SIGCLASS>24</SIGCLASS>
+    <EXPIRED>0</EXPIRED>
+    <PKALGO>DSA</PKALGO>
+    <MDALGO>SHA1</MDALGO>
+    <CREATED>1011533167</CREATED>
+    <KEYID>BD572CDCCCC07C3</KEYID>
+  </SIGNATURE>
+</OPENPGPKEY>
+
+\end{verbatim}
diff --git a/doc/tex/x509.tex b/doc/tex/x509.tex
index bcad96a8d8..bc25b8a0a2 100644
--- a/doc/tex/x509.tex
+++ b/doc/tex/x509.tex
@@ -28,9 +28,9 @@ parameters from given X.509 certificates. Some of them are:
 \end{itemize}
 
 Given the complexity of the X.509 protocols we do not expect these limited 
-functions to cover every need. Thus a function which exports X.509 certificates
-to an XML form is provided. See 
-\printfunc{gnutls_x509_certificate_to_xml}{gnutls\_x509\_certificate\_to\_xml}.
+functions to cover every need. Thus a function which converts X.509 DER certificates
+to an XML form is provided. See appendix \ref{xml} on page \pageref{xml} for
+more information.
 
 \par
 Verifying certificate\index{Verifying certificate paths} paths is also important in X.509 authentication.
diff --git a/doc/tex/x509cert.xml.tex b/doc/tex/x509cert.xml.tex
new file mode 100644
index 0000000000..d66aa4032e
--- /dev/null
+++ b/doc/tex/x509cert.xml.tex
@@ -0,0 +1,187 @@
+\begin{verbatim}
+
+<?xml version="1.0" encoding="UTF-8"?>
+<certificate type="SEQUENCE">
+  <tbsCertificate type="SEQUENCE">
+    <version type="INTEGER" encoding="HEX">02</version>
+    <serialNumber type="INTEGER" encoding="HEX">01</serialNumber>
+    <signature type="SEQUENCE">
+      <algorithm type="OBJECT ID">1 2 840 113549 1 1 4</algorithm>
+      <parameters type="ANY">
+        <md5WithRSAEncryption encoding="HEX">0500</md5WithRSAEncryption>
+      </parameters>
+    </signature>
+    <issuer type="CHOICE">
+      <rdnSequence type="SEQUENCE OF">
+        <unnamed1 type="SET OF">
+          <unnamed1 type="SEQUENCE">
+            <type type="OBJECT ID">2 5 4 6</type>
+            <value type="ANY">
+              <X520countryName>GR</X520countryName>
+            </value>
+          </unnamed1>
+        </unnamed1>
+        <unnamed2 type="SET OF">
+          <unnamed1 type="SEQUENCE">
+            <type type="OBJECT ID">2 5 4 8</type>
+            <value type="ANY">
+              <X520StateOrProvinceName>Attiki</X520StateOrProvinceName>
+            </value>
+          </unnamed1>
+        </unnamed2>
+        <unnamed3 type="SET OF">
+          <unnamed1 type="SEQUENCE">
+            <type type="OBJECT ID">2 5 4 7</type>
+            <value type="ANY">
+              <X520LocalityName>Athina</X520LocalityName>
+            </value>
+          </unnamed1>
+        </unnamed3>
+        <unnamed4 type="SET OF">
+          <unnamed1 type="SEQUENCE">
+            <type type="OBJECT ID">2 5 4 10</type>
+            <value type="ANY">
+              <X520OrganizationName>GNUTLS</X520OrganizationName>
+            </value>
+          </unnamed1>
+        </unnamed4>
+        <unnamed5 type="SET OF">
+          <unnamed1 type="SEQUENCE">
+            <type type="OBJECT ID">2 5 4 11</type>
+            <value type="ANY">
+              <X520OrganizationalUnitName>GNUTLS dev.</X520OrganizationalUnitName>
+            </value>
+          </unnamed1>
+        </unnamed5>
+        <unnamed6 type="SET OF">
+          <unnamed1 type="SEQUENCE">
+            <type type="OBJECT ID">2 5 4 3</type>
+            <value type="ANY">
+              <X520CommonName>GNUTLS TEST CA</X520CommonName>
+            </value>
+          </unnamed1>
+        </unnamed6>
+        <unnamed7 type="SET OF">
+          <unnamed1 type="SEQUENCE">
+            <type type="OBJECT ID">1 2 840 113549 1 9 1</type>
+            <value type="ANY">
+              <Pkcs9email>gnutls-dev@gnupg.org</Pkcs9email>
+            </value>
+          </unnamed1>
+        </unnamed7>
+      </rdnSequence>
+    </issuer>
+    <validity type="SEQUENCE">
+      <notBefore type="CHOICE">
+        <utcTime type="TIME">010707101845Z</utcTime>
+      </notBefore>
+      <notAfter type="CHOICE">
+        <utcTime type="TIME">020707101845Z</utcTime>
+      </notAfter>
+    </validity>
+    <subject type="CHOICE">
+      <rdnSequence type="SEQUENCE OF">
+        <unnamed1 type="SET OF">
+          <unnamed1 type="SEQUENCE">
+            <type type="OBJECT ID">2 5 4 6</type>
+            <value type="ANY">
+              <X520countryName>GR</X520countryName>
+            </value>
+          </unnamed1>
+        </unnamed1>
+        <unnamed2 type="SET OF">
+          <unnamed1 type="SEQUENCE">
+            <type type="OBJECT ID">2 5 4 8</type>
+            <value type="ANY">
+              <X520StateOrProvinceName>Attiki</X520StateOrProvinceName>
+            </value>
+          </unnamed1>
+        </unnamed2>
+        <unnamed3 type="SET OF">
+          <unnamed1 type="SEQUENCE">
+            <type type="OBJECT ID">2 5 4 7</type>
+            <value type="ANY">
+              <X520LocalityName>Athina</X520LocalityName>
+            </value>
+          </unnamed1>
+        </unnamed3>
+        <unnamed4 type="SET OF">
+          <unnamed1 type="SEQUENCE">
+            <type type="OBJECT ID">2 5 4 10</type>
+            <value type="ANY">
+              <X520OrganizationName>GNUTLS</X520OrganizationName>
+            </value>
+          </unnamed1>
+        </unnamed4>
+        <unnamed5 type="SET OF">
+          <unnamed1 type="SEQUENCE">
+            <type type="OBJECT ID">2 5 4 11</type>
+            <value type="ANY">
+              <X520OrganizationalUnitName>GNUTLS dev.</X520OrganizationalUnitName>
+            </value>
+          </unnamed1>
+        </unnamed5>
+        <unnamed6 type="SET OF">
+          <unnamed1 type="SEQUENCE">
+            <type type="OBJECT ID">2 5 4 3</type>
+            <value type="ANY">
+              <X520CommonName>localhost</X520CommonName>
+            </value>
+          </unnamed1>
+        </unnamed6>
+        <unnamed7 type="SET OF">
+          <unnamed1 type="SEQUENCE">
+            <type type="OBJECT ID">1 2 840 113549 1 9 1</type>
+            <value type="ANY">
+              <Pkcs9email>root@localhost</Pkcs9email>
+            </value>
+          </unnamed1>
+        </unnamed7>
+      </rdnSequence>
+    </subject>
+    <subjectPublicKeyInfo type="SEQUENCE">
+      <algorithm type="SEQUENCE">
+        <algorithm type="OBJECT ID">1 2 840 113549 1 1 1</algorithm>
+        <parameters type="ANY">
+          <rsaEncryption encoding="HEX">0500</rsaEncryption>
+        </parameters>
+      </algorithm>
+      <subjectPublicKey type="BIT STRING" encoding="HEX" length="1120">30818902818100D00B49EBB226D951F5CC57072199DDF287683D2DA1A0EFCC96BFF73164777C78C3991E92EDA66584E7B97BAB4BE68D595D225557E01E7E57B5C35C04B491948C5C427AD588D8C6989764996D6D44E17B65CCFC86F3B4842DE559B730C1DE3AEF1CE1A328AFF8A357EBA911E1F7E8FC1598E21E4BF721748C587F50CF46157D950203010001</subjectPublicKey>
+    </subjectPublicKeyInfo>
+    <extensions type="SEQUENCE OF">
+      <unnamed1 type="SEQUENCE">
+        <extnID type="OBJECT ID">2 5 29 35</extnID>
+        <critical type="BOOLEAN">FALSE</critical>
+        <extnValue type="SEQUENCE">
+          <keyIdentifier type="OCTET STRING" encoding="HEX">EFEE94ABC8CA577F5313DB76DC1A950093BAF3C9</keyIdentifier>
+        </extnValue>
+      </unnamed1>
+      <unnamed2 type="SEQUENCE">
+        <extnID type="OBJECT ID">2 5 29 37</extnID>
+        <critical type="BOOLEAN">FALSE</critical>
+        <extnValue type="SEQUENCE OF">
+          <unnamed1 type="OBJECT ID">1 3 6 1 5 5 7 3 1</unnamed1>
+          <unnamed2 type="OBJECT ID">1 3 6 1 5 5 7 3 2</unnamed2>
+          <unnamed3 type="OBJECT ID">1 3 6 1 4 1 311 10 3 3</unnamed3>
+          <unnamed4 type="OBJECT ID">2 16 840 1 113730 4 1</unnamed4>
+        </extnValue>
+      </unnamed2>
+      <unnamed3 type="SEQUENCE">
+        <extnID type="OBJECT ID">2 5 29 19</extnID>
+        <critical type="BOOLEAN">TRUE</critical>
+        <extnValue type="SEQUENCE">
+          <cA type="BOOLEAN">FALSE</cA>
+        </extnValue>
+      </unnamed3>
+    </extensions>
+  </tbsCertificate>
+  <signatureAlgorithm type="SEQUENCE">
+    <algorithm type="OBJECT ID">1 2 840 113549 1 1 4</algorithm>
+    <parameters type="ANY">
+      <md5WithRSAEncryption encoding="HEX">0500</md5WithRSAEncryption>
+    </parameters>
+  </signatureAlgorithm>
+  <signature type="BIT STRING" encoding="HEX" length="1024">B73945273AF2A395EC54BF5DC669D953885A9D811A3B92909D24792D36A44EC27E1C463AF8738BEFD29B311CCE8C6D9661BEC30911DAABB39B8813382B32D2E259581EBCD26C495C083984763966FF35D1DEFE432891E610C85072578DA7423244A8F5997B41A1F44E61F4F22C94375775055A5E72F25D5E4557467A91BD4251</signature>
+</certificate>
+
+\end{verbatim}