Skip to content

Commit 03229c3

Browse files
bgaifullinbgaifullin
authored
Merge pull request #57 from bgaifullin/master
Added documentation #45
2 parents 392d765 + 955961f commit 03229c3

19 files changed

+767
-65
lines changed

‎.travis.yml

+6-1
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,18 @@ install:
2121
- travis_retry pip install -e "."
2222
- pip list
2323
script: py.test tests
24+
25+
before_deploy:
26+
- travis_retry pip install Sphinx
27+
- python setup.py build_sphinx
28+
2429
deploy:
2530
skip_cleanup: true
2631
provider: pypi
2732
user: mehcode
2833
on:
2934
tags: true
3035
distributions: sdist bdist_wheel
31-
python: '3.5'
36+
python: '2.7'
3237
password:
3338
secure: Gq9Ut9FATKUSVoaTTSeecN8kWxRQjTe4K+gK/gKuRJqWzYPOG9AhCq2Nxd3rwlWedPWpfoQwmlCuCma68npVQZnsJqyNYmEUBp4xjgDXOR12q2jDlgT0SH5V23ysJydA+c5QuHGXz7INxBTSwCjD+xBe2WXRxp9RJoi8kLloFt0=

‎README.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ Linux (Debian)
3939
4040
4141
Note: There is no required version of libxml2 for ubuntu precise,
42-
so need to dowload and install it manually.
42+
so need to download and install it manually.
4343

4444
.. code-block:: bash
4545

‎doc/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SPHINXPROJ = python-xmlsec
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎doc/source/api.rst

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
API Reference
2+
=============
3+
4+
.. toctree::
5+
:maxdepth: 1
6+
7+
modules/xmlsec
8+
modules/constants
9+
modules/template
10+
modules/tree
11+
12+
13+
:ref:`contents`

‎doc/source/conf.py

+156
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# python-xmlsec documentation build configuration file, created by
4+
# sphinx-quickstart on Fri Mar 17 10:30:14 2017.
5+
#
6+
# This file is execfile()d with the current directory set to its
7+
# containing dir.
8+
#
9+
# Note that not all possible configuration values are present in this
10+
# autogenerated file.
11+
#
12+
# All configuration values have a default; values that are commented out
13+
# serve to show the default.
14+
15+
# If extensions (or modules to document with autodoc) are in another directory,
16+
# add these directories to sys.path here. If the directory is relative to the
17+
# documentation root, use os.path.abspath to make it absolute, like shown here.
18+
#
19+
import os
20+
# import sys
21+
# sys.path.insert(0, os.path.abspath('.'))
22+
23+
24+
# -- General configuration ------------------------------------------------
25+
26+
# If your documentation needs a minimal Sphinx version, state it here.
27+
#
28+
# needs_sphinx = '1.0'
29+
30+
# Add any Sphinx extension module names here, as strings. They can be
31+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
32+
# ones.
33+
extensions = ['sphinx.ext.autodoc',
34+
'sphinx.ext.viewcode']
35+
36+
# Add any paths that contain templates here, relative to this directory.
37+
templates_path = ['_templates']
38+
39+
# The suffix(es) of source filenames.
40+
# You can specify multiple suffix as a list of string:
41+
#
42+
# source_suffix = ['.rst', '.md']
43+
source_suffix = '.rst'
44+
45+
# The master toctree document.
46+
master_doc = 'index'
47+
48+
# General information about the project.
49+
project = u'python-xmlsec'
50+
copyright = u'2017, Bulat Gaifullin <[email protected]>'
51+
author = u'Bulat Gaifullin <[email protected]>'
52+
53+
# The version info for the project you're documenting, acts as replacement for
54+
# |version| and |release|, also used in various other places throughout the
55+
# built documents.
56+
#
57+
# The short X.Y version.
58+
version = os.getenv("TRAVIS_TAG", '1.0.1')
59+
# The full version, including alpha/beta/rc tags.
60+
release = version
61+
62+
# The language for content autogenerated by Sphinx. Refer to documentation
63+
# for a list of supported languages.
64+
#
65+
# This is also used if you do content translation via gettext catalogs.
66+
# Usually you set "language" from the command line for these cases.
67+
language = None
68+
69+
# List of patterns, relative to source directory, that match files and
70+
# directories to ignore when looking for source files.
71+
# This patterns also effect to html_static_path and html_extra_path
72+
exclude_patterns = []
73+
74+
# The name of the Pygments (syntax highlighting) style to use.
75+
pygments_style = 'sphinx'
76+
77+
# If true, `todo` and `todoList` produce output, else they produce nothing.
78+
todo_include_todos = False
79+
80+
81+
# -- Options for HTML output ----------------------------------------------
82+
83+
# The theme to use for HTML and HTML Help pages. See the documentation for
84+
# a list of builtin themes.
85+
#
86+
html_theme = 'nature'
87+
88+
# Theme options are theme-specific and customize the look and feel of a theme
89+
# further. For a list of options available for each theme, see the
90+
# documentation.
91+
#
92+
# html_theme_options = {}
93+
94+
# Add any paths that contain custom static files (such as style sheets) here,
95+
# relative to this directory. They are copied after the builtin static files,
96+
# so a file named "default.css" will overwrite the builtin "default.css".
97+
html_static_path = []
98+
99+
100+
# -- Options for HTMLHelp output ------------------------------------------
101+
102+
# Output file base name for HTML help builder.
103+
htmlhelp_basename = 'python-xmlsecdoc'
104+
105+
106+
# -- Options for LaTeX output ---------------------------------------------
107+
108+
latex_elements = {
109+
# The paper size ('letterpaper' or 'a4paper').
110+
#
111+
# 'papersize': 'letterpaper',
112+
113+
# The font size ('10pt', '11pt' or '12pt').
114+
#
115+
# 'pointsize': '10pt',
116+
117+
# Additional stuff for the LaTeX preamble.
118+
#
119+
# 'preamble': '',
120+
121+
# Latex figure (float) alignment
122+
#
123+
# 'figure_align': 'htbp',
124+
}
125+
126+
# Grouping the document tree into LaTeX files. List of tuples
127+
# (source start file, target name, title,
128+
# author, documentclass [howto, manual, or own class]).
129+
latex_documents = [
130+
(master_doc, 'python-xmlsec.tex', u'python-xmlsec Documentation',
131+
u'Bulat Gaifullin \\textless{}[email protected]\\textgreater{}', 'manual'),
132+
]
133+
134+
135+
# -- Options for manual page output ---------------------------------------
136+
137+
# One entry per manual page. List of tuples
138+
# (source start file, name, description, authors, manual section).
139+
man_pages = [
140+
(master_doc, 'python-xmlsec', u'python-xmlsec Documentation',
141+
[author], 1)
142+
]
143+
144+
145+
# -- Options for Texinfo output -------------------------------------------
146+
147+
# Grouping the document tree into Texinfo files. List of tuples
148+
# (source start file, target name, title, author,
149+
# dir menu entry, description, category)
150+
texinfo_documents = [
151+
(master_doc, 'python-xmlsec', u'python-xmlsec Documentation',
152+
author, 'python-xmlsec', 'One line description of project.',
153+
'Miscellaneous'),
154+
]
155+
156+
autodoc_member_order = 'groupwise'

‎doc/source/examples.rst

+116
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
Examples
2+
========
3+
4+
Decrypt
5+
-------
6+
.. code:: python
7+
8+
from lxml import etree
9+
import xmlsec
10+
11+
manager = xmlsec.KeysManager()
12+
key = xmlsec.Key.from_file('rsakey.pem', xmlsec.constants.KeyDataFormatPem)
13+
manager.add_key(key)
14+
enc_ctx = xmlsec.EncryptionContext(manager)
15+
root = etree.parse("enc1-res.xml").getroot()
16+
enc_data = xmlsec.tree.find_child(root, "EncryptedData", xmlsec.constants.EncNs)
17+
decrypted = enc_ctx.decrypt(enc_data)
18+
print(etree.tostring(decrypted))
19+
20+
21+
Encrypt
22+
-------
23+
.. code:: python
24+
25+
from lxml import etree
26+
import xmlsec
27+
28+
manager = xmlsec.KeysManager()
29+
key = xmlsec.Key.from_file('rsacert.pem', xmlsec.constants.KeyDataFormatCertPem, None)
30+
manager.add_key(key)
31+
template = etree.parse('enc1-doc.xml').getroot()
32+
enc_data = xmlsec.template.encrypted_data_create(
33+
template, xmlsec.constants.TransformAes128Cbc, type=xmlsec.constants.TypeEncContent, ns="xenc")
34+
35+
xmlsec.template.encrypted_data_ensure_cipher_value(enc_data)
36+
key_info = xmlsec.template.encrypted_data_ensure_key_info(enc_data, ns="dsig")
37+
enc_key = xmlsec.template.add_encrypted_key(key_info, xmlsec.Transform.RSA_OAEP)
38+
xmlsec.template.encrypted_data_ensure_cipher_value(enc_key)
39+
data = template.find('./Data')
40+
41+
# Encryption
42+
enc_ctx = xmlsec.EncryptionContext(manager)
43+
enc_ctx.key = xmlsec.Key.generate(xmlsec.constants.KeyDataAes, 128, xmlsec.constants.KeyDataTypeSession)
44+
enc_datsa = enc_ctx.encrypt_xml(enc_data, data)
45+
enc_method = xmlsec.tree.find_child(enc_data, xmlsec.constants.NodeEncryptionMethod, xmlsec.constants.EncNs)
46+
key_info = xmlsec.tree.find_child(enc_data, xmlsec.constants.NodeKeyInfo, xmlsec.constants.DSigNs)
47+
enc_method = xmlsec.tree.find_node(key_info, xmlsec.constants.NodeEncryptionMethod, xmlsec.constants.EncNs)
48+
cipher_value = xmlsec.tree.find_node(key_info, xmlsec.constants.NodeCipherValue, xmlsec.constants.EncNs)
49+
print(etree.tostring(cipher_value))
50+
51+
52+
Sign
53+
----
54+
.. code:: python
55+
56+
from lxml import etree
57+
import xmlsec
58+
59+
template = etree.parse('sign1-tmpl.xml').getroot()
60+
61+
signature_node = xmlsec.tree.find_node(template, xmlsec.constants.NodeSignature)
62+
ctx = xmlsec.SignatureContext()
63+
key = xmlsec.Key.from_file('rsakey.pem', xmlsec.constants.KeyDataFormatPem)
64+
ctx.key = key
65+
ctx.sign(signature_node)
66+
print(etree.tostring(template))
67+
68+
69+
Sign-Binary
70+
-----------
71+
.. code:: python
72+
73+
from lxml import etree
74+
import xmlsec
75+
76+
ctx = xmlsec.SignatureContext()
77+
key = xmlsec.Key.from_file('rsakey.pem', xmlsec.constants.KeyDataFormatPem)
78+
ctx.key = key
79+
data = b'\xa8f4dP\x82\x02\xd3\xf5.\x02\xc1\x03\xef\xc4\x86\xabC\xec\xb7>\x8e\x1f\xa3\xa3\xc5\xb9qc\xc2\x81\xb1-\xa4B\xdf\x03>\xba\xd1'
80+
sign = ctx.sign_binary(data, xmlsec.constants.TransformRsaSha1)
81+
print(sign)
82+
83+
84+
85+
Verify
86+
------
87+
.. code:: python
88+
89+
from lxml import etree
90+
import xmlsec
91+
92+
template = etree.parse('sign1-res.xml').getroot()
93+
xmlsec.tree.add_ids(template, ["ID"])
94+
signature_node = xmlsec.tree.find_node(template, xmlsec.constants.NodeSignature)
95+
# Create a digital signature context (no key manager is needed).
96+
ctx = xmlsec.SignatureContext()
97+
key = xmlsec.Key.from_file('rsapub.pem', xmlsec.constants.KeyDataFormatPem)
98+
# Set the key on the context.
99+
ctx.key = key
100+
ctx.verify(signature_node)
101+
102+
103+
Verify-Binary
104+
-------------
105+
.. code:: python
106+
107+
from lxml import etree
108+
import xmlsec
109+
110+
ctx = xmlsec.SignatureContext()
111+
key = xmlsec.Key.from_file('rsakey.pem', xmlsec.constants.KeyDataFormatPem)
112+
ctx.key = key
113+
114+
data = b'\xa8f4dP\x82\x02\xd3\xf5.\x02\xc1\x03\xef\xc4\x86\xabC\xec\xb7>\x8e\x1f\xa3\xa3\xc5\xb9qc\xc2\x81\xb1-\xa4B\xdf\x03>\xba\xd1'
115+
sign = b"h\xcb\xb1\x82\xfa`e\x89x\xe5\xc5ir\xd6\xd1Q\x9a\x0b\xeaU_G\xcc'\xa4c\xa3>\x9b27\xbf^`\xa7p\xfb\x98\xcb\x81\xd2\xb1\x0c'\x9d\xe2\n\xec\xb2<\xcf@\x98=\xe0}O8}fy\xc2\xc4\xe9\xec\x87\xf6\xc1\xde\xfd\x96*o\xab\xae\x12\xc9{\xcc\x0e\x93y\x9a\x16\x80o\x92\xeb\x02^h|\xa0\x9b<\x99_\x97\xcb\xe27\xe9u\xc3\xfa_\xcct/sTb\xa0\t\xd3\x93'\xb4\xa4\x0ez\xcbL\x14D\xdb\xe3\x84\x886\xe9J[\xe7\xce\xc0\xb1\x99\x07\x17{\xc6:\xff\x1dt\xfd\xab^2\xf7\x9e\xa4\xccT\x8e~b\xdb\x9a\x04\x04\xbaM\xfa\xbd\xec)z\xbb\x89\xd7\xb2Q\xac\xaf\x13\xdcD\xcd\n6\x92\xfao\xb9\xd9\x96$\xce\xa6\xcf\xf8\xe4Bb60\xf5\xd2a\xb1o\x8c\x0f\x8bl\x88vh\xb5h\xfa\xfa\xb66\xedQ\x10\xc4\xef\xfa\x81\xf0\xc9.^\x98\x1ePQS\x9e\xafAy\x90\xe4\x95\x03V\xc2\xa0\x18\xa5d\xc2\x15*\xb6\xd7$\xc0\t2\xa1"
116+
ctx.verify_binary(data, xmlsec.constants.TransformRsaSha1, sign)

‎doc/source/index.rst

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
.. python-xmlsec documentation master file, created by
2+
sphinx-quickstart on Fri Mar 17 10:30:14 2017.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to python-xmlsec's documentation!
7+
=========================================
8+
9+
Python bindings for the XML Security Library.
10+
11+
.. _contents:
12+
13+
Table of contents
14+
=================
15+
16+
.. toctree::
17+
:maxdepth: 2
18+
19+
install
20+
api
21+
examples
22+
23+
Indices and tables
24+
==================
25+
26+
* :ref:`genindex`
27+
* :ref:`modindex`
28+
* :ref:`search`

0 commit comments

Comments
 (0)