<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "
http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY chapter-compiling-and-linking 	SYSTEM "chapters/compiling-and-linking.sgml">
<!ENTITY chapter-init-and-shutdown 	SYSTEM "chapters/init-and-shutdown.sgml">
<!ENTITY chapter-sign-and-encrypt 	SYSTEM "chapters/sign-and-encrypt.sgml">
<!ENTITY chapter-verify-and-decrypt 	SYSTEM "chapters/verify-and-decrypt.sgml">
<!ENTITY chapter-creating-templates 	SYSTEM "chapters/creating-templates.sgml">
<!ENTITY chapter-using-keys		SYSTEM "chapters/using-keys.sgml">
<!ENTITY chapter-using-keysmngr 	SYSTEM "chapters/using-keysmngr.sgml">
<!ENTITY chapter-using-x509-certs	SYSTEM "chapters/using-x509-certs.sgml">
<!ENTITY chapter-using-transforms	SYSTEM "chapters/using-transforms.sgml">
<!ENTITY chapter-using-contexts		SYSTEM "chapters/using-contexts.sgml">
<!ENTITY chapter-new-crypto		SYSTEM "chapters/new-crypto.sgml">
<!ENTITY chapter-examples		SYSTEM "chapters/examples.sgml">

<!ENTITY xmlsec-index 			SYSTEM "xmlsec-index.sgml">

<!ENTITY xmlsec-app 			"base/app.xml">
<!ENTITY xmlsec-base64 			"base/base64.xml">
<!ENTITY xmlsec-bn 			"base/bn.xml">
<!ENTITY xmlsec-buffer 			"base/buffer.xml">
<!ENTITY xmlsec-dl 			"base/dl.xml">
<!ENTITY xmlsec-errors 			"base/errors.xml">
<!ENTITY xmlsec-io 			"base/io.xml">
<!ENTITY xmlsec-keyinfo 		"base/keyinfo.xml">
<!ENTITY xmlsec-keysdata 		"base/keysdata.xml">
<!ENTITY xmlsec-keys 			"base/keys.xml">
<!ENTITY xmlsec-keysmngr 		"base/keysmngr.xml">
<!ENTITY xmlsec-list 			"base/list.xml">
<!ENTITY xmlsec-membuf 			"base/membuf.xml">
<!ENTITY xmlsec-nodeset 		"base/nodeset.xml">
<!ENTITY xmlsec-parser 			"base/parser.xml">
<!ENTITY xmlsec-templates 		"base/templates.xml">
<!ENTITY xmlsec-transforms 		"base/transforms.xml">
<!ENTITY xmlsec-version 		"base/version.xml">
<!ENTITY xmlsec-x509                    "base/x509.xml">
<!ENTITY xmlsec-xmldsig 		"base/xmldsig.xml">
<!ENTITY xmlsec-xmlenc 			"base/xmlenc.xml">
<!ENTITY xmlsec-xmlsec 			"base/xmlsec.xml">
<!ENTITY xmlsec-xmltree 		"base/xmltree.xml">

<!ENTITY xmlsec-openssl-app 		"openssl/app.xml">
<!ENTITY xmlsec-openssl-bn 		"openssl/bn.xml">
<!ENTITY xmlsec-openssl-crypto		"openssl/crypto.xml">
<!ENTITY xmlsec-openssl-evp 		"openssl/evp.xml">
<!ENTITY xmlsec-openssl-x509 		"openssl/x509.xml">

<!ENTITY xmlsec-gnutls-app 		"gnutls/app.xml">
<!ENTITY xmlsec-gnutls-crypto 		"gnutls/crypto.xml">
<!ENTITY xmlsec-gnutls-x509 		"gnutls/x509.xml">

<!ENTITY xmlsec-gcrypt-app 		"gcrypt/app.xml">
<!ENTITY xmlsec-gcrypt-crypto 		"gcrypt/crypto.xml">

<!ENTITY xmlsec-nss-app 		"nss/app.xml">
<!ENTITY xmlsec-nss-bignum		"nss/bignum.xml">
<!ENTITY xmlsec-nss-crypto 		"nss/crypto.xml">
<!ENTITY xmlsec-nss-keysstore		"nss/keysstore.xml">
<!ENTITY xmlsec-nss-pkikeys		"nss/pkikeys.xml">
<!ENTITY xmlsec-nss-x509		"nss/x509.xml">

<!ENTITY xmlsec-mscrypto-app 		"mscrypto/app.xml">
<!ENTITY xmlsec-mscrypto-certkeys	"mscrypto/certkeys.xml">
<!ENTITY xmlsec-mscrypto-crypto 	"mscrypto/crypto.xml">
<!ENTITY xmlsec-mscrypto-keysstore	"mscrypto/keysstore.xml">
<!ENTITY xmlsec-mscrypto-x509		"mscrypto/x509.xml">

<!ENTITY xmlsec-mscng-app 		"mscng/app.xml">
<!ENTITY xmlsec-mscng-certkeys	"mscng/certkeys.xml">
<!ENTITY xmlsec-mscng-crypto 	"mscng/crypto.xml">
<!ENTITY xmlsec-mscng-keysstore	"mscng/keysstore.xml">
<!ENTITY xmlsec-mscng-x509		"mscng/x509.xml">

<!ENTITY xmlsec-example-sign1 		SYSTEM "examples/sign1.sgml">
<!ENTITY xmlsec-example-sign2 		SYSTEM "examples/sign2.sgml">
<!ENTITY xmlsec-example-sign3 		SYSTEM "examples/sign3.sgml">

<!ENTITY xmlsec-example-verify1 	SYSTEM "examples/verify1.sgml">
<!ENTITY xmlsec-example-verify2 	SYSTEM "examples/verify2.sgml">
<!ENTITY xmlsec-example-verify3 	SYSTEM "examples/verify3.sgml">
<!ENTITY xmlsec-example-verify4 	SYSTEM "examples/verify4.sgml">

<!ENTITY xmlsec-example-encrypt1 	SYSTEM "examples/encrypt1.sgml">
<!ENTITY xmlsec-example-encrypt2 	SYSTEM "examples/encrypt2.sgml">
<!ENTITY xmlsec-example-encrypt3 	SYSTEM "examples/encrypt3.sgml">

<!ENTITY xmlsec-example-decrypt1 	SYSTEM "examples/decrypt1.sgml">
<!ENTITY xmlsec-example-decrypt2 	SYSTEM "examples/decrypt2.sgml">
<!ENTITY xmlsec-example-decrypt3 	SYSTEM "examples/decrypt3.sgml">

<!ENTITY xmlsec-example-sign1-tmpl	SYSTEM "examples/sign1-tmpl.sgml">
<!ENTITY xmlsec-example-sign1-res	SYSTEM "examples/sign1-res.sgml">
<!ENTITY xmlsec-example-sign2-doc	SYSTEM "examples/sign2-doc.sgml">
<!ENTITY xmlsec-example-sign2-res	SYSTEM "examples/sign2-res.sgml">
<!ENTITY xmlsec-example-sign3-doc	SYSTEM "examples/sign3-doc.sgml">
<!ENTITY xmlsec-example-sign3-res	SYSTEM "examples/sign3-res.sgml">
<!ENTITY xmlsec-example-verify4-res 	SYSTEM "examples/verify4-res.sgml">
<!ENTITY xmlsec-example-verify4-tmpl 	SYSTEM "examples/verify4-tmpl.sgml">
<!ENTITY xmlsec-example-verify4-bad-res  SYSTEM "examples/verify4-bad-res.sgml">
<!ENTITY xmlsec-example-verify4-bad-tmpl SYSTEM "examples/verify4-bad-tmpl.sgml">

<!ENTITY xmlsec-example-encrypt1-tmpl	SYSTEM "examples/encrypt1-tmpl.sgml">
<!ENTITY xmlsec-example-encrypt1-res	SYSTEM "examples/encrypt1-res.sgml">
<!ENTITY xmlsec-example-encrypt2-doc	SYSTEM "examples/encrypt2-doc.sgml">
<!ENTITY xmlsec-example-encrypt2-res	SYSTEM "examples/encrypt2-res.sgml">
<!ENTITY xmlsec-example-encrypt3-doc	SYSTEM "examples/encrypt3-doc.sgml">
<!ENTITY xmlsec-example-encrypt3-res	SYSTEM "examples/encrypt3-res.sgml">
]>
<book id="index" xmlns:xi="http://www.w3.org/2001/XInclude">
  <bookinfo>
    <title>XML Security Library Reference Manual</title>
    <authorgroup>
      <author>
        <firstname>Aleksey</firstname>
        <surname>Sanin</surname>
        <affiliation>
	  <address>
	    <email>aleksey@aleksey.com</email>
	  </address>
        </affiliation>
      </author>
    </authorgroup>
    <copyright>
      <year>2002-2017</year>
      <holder>Aleksey Sanin</holder>
    </copyright>	
    <legalnotice>
      <para>Permission is granted to make and distribute verbatim
      copies of this manual provided the copyright notice and this
      permission notice are preserved on all copies.</para>
      <para>Permission is granted to copy and distribute modified
      versions of this manual under the conditions for verbatim
      copying, provided also that the entire resulting derived work is
      distributed under the terms of a permission notice identical to
      this one.</para>
      
      <para>Permission is granted to copy and distribute translations
      of this manual into another language, under the above conditions
      for modified versions.</para>
    </legalnotice>

    <abstract>
      <para>This manual documents the interfaces of the xmlsec
      library and has some short notes to help get you up to speed
      with using the library.</para>
    </abstract>
  </bookinfo>

  <part id="xmlsec-notes">
    <title>XML Security Library Tutorial</title>
    <chapter id="xmlsec-notes-overview">
	<title>Overview.</title>
	<para>XML Security Library provides support for XML Digital Signature 
	and XML Encryption. It is based on LibXML/LibXSLT and can use
	practicaly any crypto library (currently there is "out of the box" 
	support for OpenSSL, Microsoft Crypto API, Microsoft Cryptography API:
	Next Generation (CNG), GnuTLS, GCrypt and NSS).
	</para>
    </chapter>
    <chapter id="xmlsec-notes-structure">
	<title>XML Security Library Structure.</title>
	<para>In order to provide the an ability to use different crypto engines, 
	the XML Security Library is splitted in two parts: core library (xmlsec)
	and crypto library (xmlsec-openssl, xmlsec-mscrypt, xmlsec-mscng, xmlsec-gnutls, 
	xmlsec-gcrypt, xmlsec-nss, ...).
	<figure>
	    <title>The library structure and dependencies.</title>
	    <graphic fileref="images/structure.png" align="center"></graphic>
	</figure>	 
	</para>
	<para>The core library has no dependency on any crypto library and provides 
	implementation of all the engines as well as support for all the non 
	crypto transforms (xml parser, c14n transforms, xpath and xslt 
	transforms,...). The XML Security Crypto library provides 
	implementations for crypto transforms, crypto keys data and key 
	data stores. Application is linked with particular XML Security 
	Crypto library (or even libraries), but the actual application 
	code might be general enough so switching crypto engine would be 
	a matter of changing several #include directives.</para>
    </chapter>
    
    &chapter-compiling-and-linking;
    &chapter-init-and-shutdown;
    &chapter-sign-and-encrypt;
    &chapter-creating-templates;
    &chapter-verify-and-decrypt;
    &chapter-using-keys;
    &chapter-using-keysmngr;
    &chapter-using-x509-certs;
    &chapter-using-transforms;
    &chapter-using-contexts;
    &chapter-new-crypto;
    &chapter-examples;
    
    <chapter id="xmlsec-signature-klasses">
    <title>APPENDIX A. XML Security Library Signature Klasses.</title>
	<figure>
	    <title>XML Security Library Signature Klasses.</title>
	    <graphic fileref="images/signature-structure.png" align="center"></graphic>
	</figure>	 
    </chapter>

    <chapter id="xmlsec-encryption-klasses">
    <title>APPENDIX B. XML Security Library Encryption Klasses.</title>
	<figure>
	    <title>XML Security Library Encryption Klasses.</title>
	    <graphic fileref="images/encryption-structure.png" align="center"></graphic>
	</figure>	 
    </chapter>
  </part>

  <part id="xmlsec-reference">
    <title>XML Security Library API Reference.</title>
    
    <chapter id="xmlsec-ref">
    <title>XML Security Core Library API Reference.</title>
    <para>This section contains the API reference for xmlsec. All
    the public interfaces are documented here. This reference guide is
    build by extracting comments from the code sources. </para>

    <xi:include href="&xmlsec-app;"/>
    <xi:include href="&xmlsec-base64;"/>
    <xi:include href="&xmlsec-bn;"/>
    <xi:include href="&xmlsec-buffer;"/>
    <xi:include href="&xmlsec-dl;"/>
    <xi:include href="&xmlsec-errors;"/>
    <xi:include href="&xmlsec-io;"/>
    <xi:include href="&xmlsec-keyinfo;"/>
    <xi:include href="&xmlsec-keysdata;"/>
    <xi:include href="&xmlsec-keys;"/>
    <xi:include href="&xmlsec-keysmngr;"/>
    <xi:include href="&xmlsec-list;"/>
    <xi:include href="&xmlsec-membuf;"/>
    <xi:include href="&xmlsec-nodeset;"/>
    <xi:include href="&xmlsec-parser;"/>
    <xi:include href="&xmlsec-templates;"/>
    <xi:include href="&xmlsec-transforms;"/>
    <xi:include href="&xmlsec-version;"/>
    <xi:include href="&xmlsec-xmldsig;"/>
    <xi:include href="&xmlsec-xmlenc;"/>
    <xi:include href="&xmlsec-xmlsec;"/>
    <xi:include href="&xmlsec-xmltree;"/>
    <xi:include href="&xmlsec-x509;"/>
    </chapter>

    <chapter id="xmlsec-openssl-ref">
    <title>XML Security Library for OpenSLL API Reference.</title>
    <para>This section contains the API reference for xmlsec-openssl. All
    the public interfaces are documented here. This reference guide is
    build by extracting comments from the code sources. </para>

    <xi:include href="&xmlsec-openssl-app;"/>
    <xi:include href="&xmlsec-openssl-bn;"/>
    <xi:include href="&xmlsec-openssl-crypto;"/>
    <xi:include href="&xmlsec-openssl-evp;"/>
    <xi:include href="&xmlsec-openssl-x509;"/>
    </chapter>

    <chapter id="xmlsec-gnutls-ref">
    <title>XML Security Library for GnuTLS API Reference.</title>
    <para>This section contains the API reference for xmlsec-gnutls. All
    the public interfaces are documented here. This reference guide is
    build by extracting comments from the code sources. </para>

    <xi:include href="&xmlsec-gnutls-app;"/>
    <xi:include href="&xmlsec-gnutls-crypto;"/>
    <xi:include href="&xmlsec-gnutls-x509;"/>
    </chapter>

    <chapter id="xmlsec-gcrypt-ref">
    <title>XML Security Library for GCrypt API Reference.</title>
    <para>This section contains the API reference for xmlsec-gcrypt. All
    the public interfaces are documented here. This reference guide is
    build by extracting comments from the code sources. </para>

    <xi:include href="&xmlsec-gcrypt-app;"/>
    <xi:include href="&xmlsec-gcrypt-crypto;"/>
    </chapter>

    <chapter id="xmlsec-nss-ref">
    <title>XML Security Library for NSS API Reference.</title>
    <para>This section contains the API reference for xmlsec-nss. All
    the public interfaces are documented here. This reference guide is
    build by extracting comments from the code sources. </para>

    <xi:include href="&xmlsec-nss-app;"/>
    <xi:include href="&xmlsec-nss-bignum;"/>
    <xi:include href="&xmlsec-nss-crypto;"/>
    <xi:include href="&xmlsec-nss-keysstore;"/>
    <xi:include href="&xmlsec-nss-pkikeys;"/>
    <xi:include href="&xmlsec-nss-x509;"/>
    </chapter>

    <chapter id="xmlsec-mscrypto-ref">
    <title>XML Security Library for Microsoft Crypto API Reference.</title>
    <para>This section contains the API reference for xmlsec-mscrypto (based on
    Microsoft Crypto API). All the public interfaces are documented here.
    This reference guide is build by extracting comments from the code sources.
    </para>

    <xi:include href="&xmlsec-mscrypto-app;"/>
    <xi:include href="&xmlsec-mscrypto-certkeys;"/>
    <xi:include href="&xmlsec-mscrypto-crypto;"/>
    <xi:include href="&xmlsec-mscrypto-keysstore;"/>
    <xi:include href="&xmlsec-mscrypto-x509;"/>
    </chapter>
    

    <chapter id="xmlsec-msccng-ref">
    <title>XML Security Library for Microsoft Cryptography API: Next Generation (CNG) Reference.</title>
    <para>This section contains the API reference for xmlsec-mscng (based on
    <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa376210(v=vs.85).aspx">Microsoft 
    Cryptography API: Next Generation (CNG)</a>). All the public interfaces are
    documented here. This reference guide is build by extracting comments from
    the code sources. </para>

    <xi:include href="&xmlsec-mscng-app;"/>
    <xi:include href="&xmlsec-mscng-certkeys;"/>
    <xi:include href="&xmlsec-mscng-crypto;"/>
    <xi:include href="&xmlsec-mscng-keysstore;"/>
    <xi:include href="&xmlsec-mscng-x509;"/>
    </chapter>

    <chapter id="xmlsec-index">
    <title>XML Security Library Reference Index</title>
    <para>
	<itemizedlist>
        &xmlsec-index;
	</itemizedlist>
    </para>	
    </chapter>
  </part>
</book>
