tyler.durden
/
PyKMIP
mirror of https://github.com/OpenKMIP/PyKMIP.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add Sphinx documentation 

This change adds a new documentation suite managed by Sphinx.
Information on the library, including client and server details,
a glossary, and development guidelines are included.
This commit is contained in:
Peter Hamilton 2017-10-23 14:32:32 -04:00
parent cf6ad944b7
commit 0dcfe8918c
16 changed files with 4208 additions and 637 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
CHANGES.txt → CHANGELOG.rst
View File

@ -1,7 +1,18 @@
0.8 - master
- This version is under active development and has not been released.
=========
Changelog
=========
0.7.0 - November 14, 2017
.. _v0.8:
0.8 - `master`_
~~~~~~~~~~~~~~~
.. note:: This version is not yet released and is under active development.
.. _v0.7:
0.7 - November 14, 2017
~~~~~~~~~~~~~~~~~~~~~~~
* Add support for Python 3.6
* Add support for the InitialDate attribute
* Add server support for the GetAttributeList operation
@ -28,7 +39,10 @@
* Fix bug with socket interrupt handling under Python 3.5
* Fix bug with detached instance errors in the server test suite
0.6.0 - December 14, 2016
.. _v0.6:
0.6 - December 14, 2016
~~~~~~~~~~~~~~~~~~~~~~~~~
* Add support for Python 3.5
* Add support for the State and OperationPolicyName attributes
* Add server support for the Activate and GetAttributes operations
@ -46,7 +60,10 @@
* Fix bug with deprecated usage of the bandit config file
* Fix bug with ProxyKmipClient registering unset object attributes
0.5.0 - April 14, 2016
.. _v0.5:
0.5 - April 14, 2016
~~~~~~~~~~~~~~~~~~~~~~
* Add KmipServer server implementation
* Add KmipSession to manage threaded client/server connections
* Add KmipEngine for processing core server application logic
@ -69,7 +86,10 @@
* Fix bug with Locate payload parsing optional values
* Fix bug with DateTime string tests and move to UTC representation
.. _v0.4.1:
0.4.1 - December 2, 2015
~~~~~~~~~~~~~~~~~~~~~~~~
* Add support for the GetAttributeList operation
* Add integration with Travis CI, Codecov/Coveralls, and Bandit
* Add client/server failover support using multiple IP addresses
@ -79,7 +99,10 @@
* Remove use of exec when handling library version numbers
* Remove broken server script
0.4.0 - August 14, 2015
.. _v0.4:
0.4 - August 14, 2015
~~~~~~~~~~~~~~~~~~~~~
* Add the official Pie API for a simpler KMIP interface
* Add the ProxyKmipClient implementation of the Pie API
* Add key, secret, and opaque objects to the Pie object hierarchy
@ -94,7 +117,10 @@
* Fix bug with dangling file handle when setting __version__
* Fix bug with dangling socket connection upon client destruction
.. _v0.3.3:
0.3.3 - June 25, 2015
~~~~~~~~~~~~~~~~~~~~~
* Add the core ManagedObject class hierarchy for the new Pie API
* Add updated Boolean primitive implementation and test suite
* Add integration tests for symmetric key creation and registration
@ -105,7 +131,10 @@
* Fix bug with relative path use for version number handling
* Fix bug with Integer primitive breaking on valid long integer values
.. _v0.3.2:
0.3.2 - June 11, 2015
~~~~~~~~~~~~~~~~~~~~~
* Add support for registering and retrieving Certificates
* Update unit demos to work with Certificates
* Reorganize test suite into unit and integration test suites
@ -113,12 +142,18 @@
* Fix bug with incorrect KeyMaterialStruct tag
* Fix bug causing infinite recursion with object inheritance
.. _v0.3.1:
0.3.1 - April 23, 2015
~~~~~~~~~~~~~~~~~~~~~~
* Add KMIP profile information to the client
* Add support for registering/retrieving SecretData and Opaque objects
* Update the SecretFactory to build Public/PrivateKeys with user data
0.3.0 - March 14, 2015
.. _v0.3:
0.3 - March 14, 2015
~~~~~~~~~~~~~~~~~~~~
* Add client support for the DiscoverVersions and Query operations
* Add client support for the CreateKeyPair and ReKeyKeyPair operations
* Add support for registering and retrieving PublicKeys and PrivateKeys
@ -131,22 +166,36 @@
* Fix bug with unindexed format strings (impacts Python 2.6)
* Fix missing certificate file issue when installing library from PyPI
0.2.0 - November 17, 2014
.. _v0.2:
0.2 - November 17, 2014
~~~~~~~~~~~~~~~~~~~~~~~~~
* Add configuration file support
* Add client support for the Locate operation
* Update README with additional information and reStructuredText format
.. _v0.1.1:
0.1.1 - September 12, 2014
~~~~~~~~~~~~~~~~~~~~~~~~~~
* Fix bug with auto-installing third party dependencies
.. _v0.1:
0.1.0 - August 28, 2014
~~~~~~~~~~~~~~~~~~~~~~~
* Add support for Python 3.3 and 3.4
* Add support for KMIP client/server SSL connections
* Remove all Thrift library dependencies
.. _v0.0.1:
0.0.1 - August 12, 2014
~~~~~~~~~~~~~~~~~~~~~~~
* Initial release
* Add support for Python 2.6 and 2.7
* Add KMIP client and server
* Add client/server support for Create, Get, Register, and Destroy operations
* Add unit test suite
* Add unit test suite
.. _`master`: https://github.com/openkmip/pykmip/

20
docs/Makefile Normal file
View File

@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = python -msphinx
SPHINXPROJ = PyKMIP
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

359
docs/conf.py
View File

@ -1,359 +0,0 @@
# -*- coding: utf-8 -*-
#
# PyKMIP documentation build configuration file, created by
# sphinx-quickstart on Mon Jan 25 17:12:29 2016.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.mathjax',
'sphinx.ext.ifconfig',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'PyKMIP'
copyright = u'2016, JHUAPL'
author = u'JHUAPL'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'0.4'
# The full version, including alpha/beta/rc tags.
release = u'0.4.1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
#html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# Now only 'ja' uses this config value
#html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'PyKMIPdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
# Latex figure (float) alignment
#'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'PyKMIP.tex', u'PyKMIP Documentation',
u'JHUAPL', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'pykmip', u'PyKMIP Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'PyKMIP', u'PyKMIP Documentation',
author, 'PyKMIP', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
# -- Options for Epub output ----------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
epub_author = author
epub_publisher = author
epub_copyright = copyright
# The basename for the epub file. It defaults to the project name.
#epub_basename = project
# The HTML theme for the epub output. Since the default themes are not
# optimized for small screen space, using the same theme for HTML and epub
# output is usually not wise. This defaults to 'epub', a theme designed to save
# visual space.
#epub_theme = 'epub'
# The language of the text. It defaults to the language option
# or 'en' if the language is not set.
#epub_language = ''
# The scheme of the identifier. Typical schemes are ISBN or URL.
#epub_scheme = ''
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#epub_identifier = ''
# A unique identification for the text.
#epub_uid = ''
# A tuple containing the cover image and cover page html template filenames.
#epub_cover = ()
# A sequence of (type, uri, title) tuples for the guide element of content.opf.
#epub_guide = ()
# HTML files that should be inserted before the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_pre_files = []
# HTML files that should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files = []
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3
# Allow duplicate toc entries.
#epub_tocdup = True
# Choose between 'default' and 'includehidden'.
#epub_tocscope = 'default'
# Fix unsupported image types using the Pillow.
#epub_fix_images = False
# Scale large images.
#epub_max_image_width = 0
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#epub_show_urls = 'inline'
# If false, no index is generated.
#epub_use_index = True

22
docs/index.rst
View File

@ -1,22 +0,0 @@
.. PyKMIP documentation master file, created by
sphinx-quickstart on Mon Jan 25 17:12:29 2016.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to PyKMIP's documentation!
==================================
Contents:
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

259
docs/make.bat
View File

@ -1,263 +1,36 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set BUILDDIR=_build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
set I18NSPHINXOPTS=%SPHINXOPTS% .
if NOT "%PAPER%" == "" (
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
set SPHINXBUILD=python -msphinx
)
set SOURCEDIR=source
set BUILDDIR=build
set SPHINXPROJ=PyKMIP
if "%1" == "" goto help
if "%1" == "help" (
:help
echo.Please use `make ^<target^>` where ^<target^> is one of
echo. html to make standalone HTML files
echo. dirhtml to make HTML files named index.html in directories
echo. singlehtml to make a single large HTML file
echo. pickle to make pickle files
echo. json to make JSON files
echo. htmlhelp to make HTML files and a HTML help project
echo. qthelp to make HTML files and a qthelp project
echo. devhelp to make HTML files and a Devhelp project
echo. epub to make an epub
echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
echo. text to make text files
echo. man to make manual pages
echo. texinfo to make Texinfo files
echo. gettext to make PO message catalogs
echo. changes to make an overview over all changed/added/deprecated items
echo. xml to make Docutils-native XML files
echo. pseudoxml to make pseudoxml-XML files for display purposes
echo. linkcheck to check all external links for integrity
echo. doctest to run all doctests embedded in the documentation if enabled
echo. coverage to run coverage check of the documentation if enabled
goto end
)
if "%1" == "clean" (
for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
del /q /s %BUILDDIR%\*
goto end
)
REM Check if sphinx-build is available and fallback to Python version if any
%SPHINXBUILD% 1>NUL 2>NUL
if errorlevel 9009 goto sphinx_python
goto sphinx_ok
:sphinx_python
set SPHINXBUILD=python -m sphinx.__init__
%SPHINXBUILD% 2> nul
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.The Sphinx module was not found. Make sure you have Sphinx installed,
echo.then set the SPHINXBUILD environment variable to point to the full
echo.path of the 'sphinx-build' executable. Alternatively you may add the
echo.Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
:sphinx_ok
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
goto end
if "%1" == "html" (
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
goto end
)
if "%1" == "dirhtml" (
%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
goto end
)
if "%1" == "singlehtml" (
%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
goto end
)
if "%1" == "pickle" (
%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the pickle files.
goto end
)
if "%1" == "json" (
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the JSON files.
goto end
)
if "%1" == "htmlhelp" (
%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run HTML Help Workshop with the ^
.hhp project file in %BUILDDIR%/htmlhelp.
goto end
)
if "%1" == "qthelp" (
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run "qcollectiongenerator" with the ^
.qhcp project file in %BUILDDIR%/qthelp, like this:
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PyKMIP.qhcp
echo.To view the help file:
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PyKMIP.ghc
goto end
)
if "%1" == "devhelp" (
%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished.
goto end
)
if "%1" == "epub" (
%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The epub file is in %BUILDDIR%/epub.
goto end
)
if "%1" == "latex" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
if errorlevel 1 exit /b 1
echo.
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "latexpdf" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
cd %BUILDDIR%/latex
make all-pdf
cd %~dp0
echo.
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "latexpdfja" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
cd %BUILDDIR%/latex
make all-pdf-ja
cd %~dp0
echo.
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "text" (
%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The text files are in %BUILDDIR%/text.
goto end
)
if "%1" == "man" (
%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The manual pages are in %BUILDDIR%/man.
goto end
)
if "%1" == "texinfo" (
%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
goto end
)
if "%1" == "gettext" (
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
goto end
)
if "%1" == "changes" (
%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
if errorlevel 1 exit /b 1
echo.
echo.The overview file is in %BUILDDIR%/changes.
goto end
)
if "%1" == "linkcheck" (
%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
if errorlevel 1 exit /b 1
echo.
echo.Link check complete; look for any errors in the above output ^
or in %BUILDDIR%/linkcheck/output.txt.
goto end
)
if "%1" == "doctest" (
%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
if errorlevel 1 exit /b 1
echo.
echo.Testing of doctests in the sources finished, look at the ^
results in %BUILDDIR%/doctest/output.txt.
goto end
)
if "%1" == "coverage" (
%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
if errorlevel 1 exit /b 1
echo.
echo.Testing of coverage in the sources finished, look at the ^
results in %BUILDDIR%/coverage/python.txt.
goto end
)
if "%1" == "xml" (
%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The XML files are in %BUILDDIR%/xml.
goto end
)
if "%1" == "pseudoxml" (
%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
goto end
)
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
:end
popd

1
docs/source/changelog.rst Normal file
View File

@ -0,0 +1 @@
.. include:: ../../CHANGELOG.rst

974
docs/source/client.rst Normal file
View File

@ -0,0 +1,974 @@
Client
======
The PyKMIP client allows developers to connect to a KMIP-compliant key
management server and conduct key management operations.
.. py:module:: kmip.pie.client
.. py:class:: ProxyKmipClient(hostname=None, port=None, cert=None, key=None, ca=None, ssl_version=None, username=None, password=None, config='client')
A simplified KMIP client for conducting KMIP operations.
The ProxyKmipClient is a simpler KMIP client supporting various KMIP
operations. It wraps the original KMIPProxy, reducing the boilerplate
needed to deploy PyKMIP in client applications. The underlying proxy
client is responsible for setting up the underlying socket connection
and for writing/reading data to/from the socket.
Like the KMIPProxy, the ProxyKmipClient is not thread-safe.
:param string hostname: The host or IP address of a KMIP appliance.
Optional, defaults to None.
:param int port: The port number used to establish a connection to a
KMIP appliance. Usually 5696 for KMIP applications. Optional,
defaults to None.
:param string cert: The path to the client's certificate. Optional,
defaults to None.
:param string key: The path to the key for the client's certificate.
Optional, defaults to None.
:param string ca: The path to the CA certificate used to verify the
server's certificate. Optional, defaults to None.
:param string ssl_version: The name of the ssl version to use for the
connection. Example: 'PROTOCOL_SSLv23'. Optional, defaults to None.
:param string username: The username of the KMIP appliance account to
use for operations. Optional, defaults to None.
:param string password: The password of the KMIP appliance account to
use for operations. Optional, defaults to None.
:param string config: The name of a section in the PyKMIP configuration
file. Use to load a specific set of configuration settings from the
configuration file, instead of specifying them manually. Optional,
defaults to the default client section, 'client'.
.. py:method:: open()
Open the client connection.
:raises kmip.pie.exceptions.ClientConnectionFailure: This is raised if
the client connection is already open.
:raises Exception: This is raised if an error occurs while trying to
open the connection.
.. py:method:: close()
Close the client connection.
:raises Exception: This is raised if an error occurs while trying to
close the connection.
.. py:method:: create(algorithm, length, operation_policy_name=None, name=None, cryptographic_usage_mask=None)
Create a symmetric key on a KMIP appliance.
:param algorithm: A :class:`kmip.core.enums.CryptographicAlgorithm`
enumeration defining the algorithm to use to generate the symmetric
key. See :term:`cryptographic_algorithm` for more information.
:param int length: The length in bits for the symmetric key.
:param string operation_policy_name: The name of the operation policy
to use for the new symmetric key. Optional, defaults to None
:param string name: The name to give the key. Optional, defaults to
None.
:param list cryptographic_usage_mask: A list of
:class:`kmip.core.enums.CryptographicUsageMask` enumerations
defining how the created key should be used. Optional, defaults to
None. See :term:`cryptographic_usage_mask` for more information.
:return: The string uid of the newly created symmetric key.
:raises kmip.pie.exceptions.ClientConnectionNotOpen: This is raised if
the client connection is unusable.
:raises kmip.pie.exceptions.KmipOperationFailure: This is raised if the
operation result is a failure.
:raises TypeError: This is raised if the input arguments are invalid.
Creating an 256-bit AES key used for encryption and decryption would
look like this:
.. code-block:: python
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> with c:
... key_id = c.create(
... enums.CryptographicAlgorithm.AES,
... 256,
... operation_policy_name='default',
... name='Test_256_AES_Symmetric_Key',
... cryptographic_usage_mask=[
... enums.CryptographicUsageMask.ENCRYPT,
... enums.CryptographicUsageMask.DECRYPT
... ]
... )
'449'
.. py:method:: create_key_pair(algorithm, length, operation_policy_name=None, public_name=None, public_usage_mask=None, private_name=None, private_usage_mask=None)
Create an asymmetric key pair on a KMIP appliance.
:param algorithm: A :class:`kmip.core.enums.CryptographicAlgorithm`
enumeration defining the algorithm to use to generate the key pair.
See :term:`cryptographic_algorithm` for more information.
:param int length: The length in bits for the key pair.
:param string operation_policy_name: The name of the operation policy
to use for the new key pair. Optional, defaults to None.
:param string public_name: The name to give the public key. Optional,
defaults to None.
:param list public_usage_mask: A list of
:class:`kmip.core.enums.CryptographicUsageMask` enumerations
indicating how the public key should be used. Optional, defaults to
None. See :term:`cryptographic_usage_mask` for more information.
:param string private_name: The name to give the public key. Optional,
defaults to None.
:param list private_usage_mask: A list of
:class:`kmip.core.enums.CryptographicUsageMask` enumerations
indicating how the private key should be used. Optional, defaults
to None. See :term:`cryptographic_usage_mask` for more information.
:return: The string uid of the newly created public key.
:return: The string uid of the newly created private key.
:raises kmip.pie.exceptions.ClientConnectionNotOpen: This is raised if
the client connection is unusable.
:raises kmip.pie.exceptions.KmipOperationFailure: This is raised if the
operation result is a failure
:raises TypeError: This is raised if the input arguments are invalid.
Creating an 2048-bit RSA key pair to be used for signing and signature
verification would look like this:
.. code-block:: python
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> with c:
... key_id = c.create_key_pair(
... enums.CryptographicAlgorithm.RSA,
... 2048,
... operation_policy_name='default',
... public_name='Test_2048_RSA_Public_Key',
... public_usage_mask=[
... enums.CryptographicUsageMask.VERIFY
... ],
... private_name='Test_2048_RSA_Private_Key',
... private_usage_mask=[
... enums.CryptographicUsageMask.SIGN
... ]
... )
('450', '451')
.. py:method:: register(managed_object)
Register a managed object with a KMIP appliance.
:param managed_object: A :class:`kmip.pie.objects.ManagedObject`
instance to register with the server.
:return: The string uid of the newly registered managed object.
:raises kmip.pie.exceptions.ClientConnectionNotOpen: This is raised if
the client connection is unusable.
:raises kmip.pie.exceptions.KmipOperationFailure: This is raised if the
operation result is a failure.
:raises TypeError: This is raised if the input argument is invalid.
Registering an existing 128-bit AES symmetric key would look like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> symmetric_key = objects.SymmetricKey(
... enums.CryptographicAlgorithm.AES,
... 128,
... (
... b'\x00\x01\x02\x03\x04\x05\x06\x07'
... b'\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F'
... )
... )
>>> with c:
... c.register(symmetric_key)
...
'452'
.. py:method:: derive_key(object_type, unique_identifiers, derivation_method, derivation_parameters, **kwargs)
Derive a new key or secret data from existing managed objects.
:param object_type: A :class:`kmip.core.enums.ObjectType` enumeration
specifying what type of object to derive. Only SymmetricKeys and
SecretData can be specified. Required. See :term:`object_type` for
more information.
:param list unique_identifiers: A list of strings specifying the
unique IDs of the existing managed objects to use for derivation.
Multiple objects can be specified to fit the requirements of the
given derivation method. Required.
:param derivation_method: A :class:`kmip.core.enums.DerivationMethod`
enumeration specifying how key derivation should be done. Required.
See :term:`derivation_method` for more information.
:param dict `derivation_parameters`: A dictionary containing various
settings for the key derivation process. Required. See
:term:`derivation_parameters` for more information.
:param `**kwargs`: A placeholder for object attributes that should be set
on the newly derived object. See the examples below for more
information.
:return: The unique string ID of the newly derived object.
:raises kmip.pie.exceptions.ClientConnectionNotOpen: This is raised if
the client connection is unusable.
:raises kmip.pie.exceptions.KmipOperationFailure: This is raised if the
operation result is a failure.
:raises TypeError: This is raised if the input arguments are invalid.
Deriving a new key using PBKDF2 would look like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> secret_data = objects.SecretData(
... b'password',
... enums.SecretDataType.PASSWORD,
... masks=[
... enums.CryptographicUsageMask.DERIVE_KEY
... ]
... )
>>> with c:
... password_id = c.register(secret_data)
... c.activate(password_id)
... c.derive_key(
... enums.ObjectType.SYMMETRIC_KEY,
... [password_id],
... enums.DerivationMethod.PBKDF2,
... {
... 'cryptographic_parameters': {
... 'hashing_algorithm':
... enums.HashingAlgorithm.SHA_1
... },
... 'salt': b'salt',
... 'iteration_count': 4096
... },
... cryptographic_length=128,
... cryptographic_algorithm=enums.CryptographicAlgorithm.AES
... )
...
'454'
Deriving a new secret using encryption would look like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> key = objects.SymmetricKey(
... enums.CryptographicAlgorithm.BLOWFISH,
... 128,
... (
... b'\x01\x23\x45\x67\x89\xAB\xCD\xEF'
... b'\xF0\xE1\xD2\xC3\xB4\xA5\x96\x87'
... ),
... masks=[
... enums.CryptographicUsageMask.DERIVE_KEY
... ]
... )
>>> with c:
... key_id = c.register(key)
... c.activate(key_id)
... c.derive_key(
... enums.ObjectType.SECRET_DATA,
... [key_id],
... enums.DerivationMethod.ENCRYPT,
... {
... 'cryptographic_parameters': {
... 'block_cipher_mode': enums.BlockCipherMode.CBC,
... 'padding_method': enums.PaddingMethod.PKCS5,
... 'cryptographic_algorithm':
... enums.CryptographicAlgorithm.BLOWFISH
... },
... 'initialization_vector': (
... b'\xFE\xDC\xBA\x98\x76\x54\x32\x10'
... ),
... 'derivation_data': (
... b'\x37\x36\x35\x34\x33\x32\x31\x20'
... b'\x4E\x6F\x77\x20\x69\x73\x20\x74'
... b'\x68\x65\x20\x74\x69\x6D\x65\x20'
... b'\x66\x6F\x72\x20\x00'
... )
... },
... cryptographic_length=256
... )
...
'456'
Deriving a new key using NIST 800 108-C would look like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> key = objects.SymmetricKey(
... enums.CryptographicAlgorithm.AES,
... 512,
... (
... b'\xdd\x5d\xbd\x45\x59\x3e\xe2\xac'
... b'\x13\x97\x48\xe7\x64\x5b\x45\x0f'
... b'\x22\x3d\x2f\xf2\x97\xb7\x3f\xd7'
... b'\x1c\xbc\xeb\xe7\x1d\x41\x65\x3c'
... b'\x95\x0b\x88\x50\x0d\xe5\x32\x2d'
... b'\x99\xef\x18\xdf\xdd\x30\x42\x82'
... b'\x94\xc4\xb3\x09\x4f\x4c\x95\x43'
... b'\x34\xe5\x93\xbd\x98\x2e\xc6\x14'
... ),
... masks=[
... enums.CryptographicUsageMask.DERIVE_KEY
... ]
... )
>>> with c:
... key_id = c.register(key)
... c.activate(key_id)
... c.derive_key(
... enums.ObjectType.SYMMETRIC_KEY,
... [key_id],
... enums.DerivationMethod.NIST800_108_C,
... {
... 'cryptographic_parameters': {
... 'hashing_algorithm':
... enums.HashingAlgorithm.SHA_512
... },
... 'derivation_data': (
... b'\xb5\x0b\x0c\x96\x3c\x6b\x30\x34'
... b'\xb8\xcf\x19\xcd\x3f\x5c\x4e\xbe'
... b'\x4f\x49\x85\xaf\x0c\x03\xe5\x75'
... b'\xdb\x62\xe6\xfd\xf1\xec\xfe\x4f'
... b'\x28\xb9\x5d\x7c\xe1\x6d\xf8\x58'
... b'\x43\x24\x6e\x15\x57\xce\x95\xbb'
... b'\x26\xcc\x9a\x21\x97\x4b\xbd\x2e'
... b'\xb6\x9e\x83\x55'
... )
... },
... cryptographic_length=128,
... cryptographic_algorithm=enums.CryptographicAlgorithm.AES
... )
...
'458'
Deriving a new secret using HMAC would look like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> secret = objects.SecretData(
... (
... b'\x0c\x0c\x0c\x0c\x0c\x0c\x0c\x0c'
... b'\x0c\x0c\x0c\x0c\x0c\x0c\x0c\x0c'
... b'\x0c\x0c\x0c\x0c\x0c\x0c'
... ),
... enums.SecretDataType.SEED,
... masks=[
... enums.CryptographicUsageMask.DERIVE_KEY
... ]
... )
>>> with c:
... secret_id = c.register(secret)
... c.activate(secret_id)
... c.derive_key(
... enums.ObjectType.SECRET_DATA,
... [secret_id],
... enums.DerivationMethod.HMAC,
... {
... 'cryptographic_parameters': {
... 'hashing_algorithm':
... enums.HashingAlgorithm.SHA_1
... },
... 'derivation_data': b'',
... 'salt': b''
... },
... cryptographic_length=336
... )
...
'460'
.. py:method:: locate(maximum_items=None, storage_status_mask=None, object_group_member=None, attributes=None)
Documentation coming soon.
.. py:method:: get(uid=None, key_wrapping_specification=None)
Get a managed object from a KMIP appliance.
:param string uid: The unique ID of the managed object to retrieve.
:param dict key_wrapping_specification: A dictionary containing the
settings to use to wrap the object before retrieval. Optional,
defaults to None. See :term:`key_wrapping_specification` for
more information.
:return: An :class:`kmip.pie.objects.ManagedObject` instance.
:raises kmip.pie.exceptions.ClientConnectionNotOpen: This is raised if
the client connection is unusable.
:raises kmip.pie.exceptions.KmipOperationFailure: This is raised if the
operation result is a failure.
:raises TypeError: This is raised if the input argument is invalid.
Getting a symmetric key would look like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> symmetric_key = objects.SymmetricKey(
... enums.CryptographicAlgorithm.AES,
... 128,
... (
... b'\x00\x01\x02\x03\x04\x05\x06\x07'
... b'\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F'
... )
... )
>>> with c:
... key_id = c.register(symmetric_key)
... c.get(key_id)
SymmetricKey(...)
Getting a wrapped symmetric key would look like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> symmetric_key = objects.SymmetricKey(
... enums.CryptographicAlgorithm.AES,
... 128,
... (
... b'\x00\x01\x02\x03\x04\x05\x06\x07'
... b'\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F'
... )
... )
>>> wrapping_key = objects.SymmetricKey(
... enums.CryptographicAlgorithm.AES,
... 128,
... (
... b'\x00\x11\x22\x33\x44\x55\x66\x77'
... b'\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF'
... ),
... [
... enums.CryptographicUsageMask.WRAP_KEY
... ]
... )
>>> with c:
... key_id = c.register(symmetric_key)
... wrapping_key_id = c.register(wrapping_key)
... c.activate(wrapping_key_id)
... c.get(
... key_id,
... key_wrapping_specification={
... 'wrapping_method': enums.WrappingMethod.ENCRYPT,
... 'encryption_key_information': {
... 'unique_identifier': wrapping_key_id,
... 'cryptographic_parameters': {
... 'block_cipher_mode':
... enums.BlockCipherMode.NIST_KEY_WRAP
... }
... },
... 'encoding_option': enums.EncodingOption.NO_ENCODING
... }
... )
SymmetricKey(...)
.. py:method:: get_attributes(uid=None, attribute_names=None)
Get the attributes associated with a managed object.
If the uid is not specified, the appliance will use the ID placeholder
by default.
If the attribute_names list is not specified, the appliance will
return all viable attributes for the managed object.
:param string uid: The unique ID of the managed object with which the
retrieved attributes should be associated. Optional, defaults to
None.
:param list attribute_names: A list of string attribute names
indicating which attributes should be retrieved. Optional, defaults
to None.
:return: The string ID of the object the attributes belong to.
:return: A list of :class:`kmip.core.objects.Attribute` instances.
:raises kmip.pie.exceptions.ClientConnectionNotOpen: This is raised if
the client connection is unusable.
:raises kmip.pie.exceptions.KmipOperationFailure: This is raised if the
operation result is a failure.
:raises TypeError: This is raised if the input argument is invalid.
Retrieving all of the attributes for a managed object would look like
this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> symmetric_key = objects.SymmetricKey(
... enums.CryptographicAlgorithm.AES,
... 128,
... (
... b'\x00\x01\x02\x03\x04\x05\x06\x07'
... b'\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F'
... )
... )
>>> with c:
... key_id = c.register(symmetric_key)
... c.get_attributes(key_id)
('458', [Attribute(...), Attribute(...), ...])
Retrieving only a specific attribute for a managed object would look
like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> symmetric_key = objects.SymmetricKey(
... enums.CryptographicAlgorithm.AES,
... 128,
... (
... b'\x00\x01\x02\x03\x04\x05\x06\x07'
... b'\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F'
... )
... )
>>> with c:
... key_id = c.register(symmetric_key)
... c.get_attributes(key_id, ['Cryptographic Length'])
...
(
'458',
[
Attribute(
attribute_name=AttributeName(value='Cryptographic Length'),
attribute_index=None,
attribute_value=CryptographicLength(value=128)
)
]
)
.. py:method:: get_attribute_list(uid=None)
Get the names of the attributes associated with a managed object.
If the uid is not specified, the appliance will use the ID placeholder
by default.
:param string uid: The unique ID of the managed object with which the
retrieved attribute names should be associated. Optional, defaults
to None.
Retrieving the list of attribute names for a symmetric key would look
like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> symmetric_key = objects.SymmetricKey(
... enums.CryptographicAlgorithm.AES,
... 128,
... (
... b'\x00\x01\x02\x03\x04\x05\x06\x07'
... b'\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F'
... )
... )
>>> with c:
... key_id = c.register(symmetric_key)
... c.get_attribute_list(key_id)
...
[
'Cryptographic Algorithm',
'Cryptographic Length',
'Cryptographic Usage Mask',
'Initial Date',
'Object Type',
'Operation Policy Name',
'State',
'Unique Identifier'
]
.. py:method:: activate(uid=None)
Activate a managed object stored by a KMIP appliance.
:param string uid: The unique ID of the managed object to activate.
Optional, defaults to None.
:return: None
:raises kmip.pie.exceptions.ClientConnectionNotOpen: This is raised if
the client connection is unusable.
:raises kmip.pie.exceptions.KmipOperationFailure: This is raised if the
operation result is a failure.
:raises TypeError: This is raised if the input argument is invalid.
Activating a symmetric key would look like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> symmetric_key = objects.SymmetricKey(
... enums.CryptographicAlgorithm.AES,
... 128,
... (
... b'\x00\x01\x02\x03\x04\x05\x06\x07'
... b'\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F'
... )
... )
>>> with c:
... key_id = c.register(symmetric_key)
... c.activate(key_id)
.. py:method:: revoke(revocation_reason, uid=None, revocation_message=None, compromise_occurrence_date=None)
Revoke a managed object stored by a KMIP appliance.
Activated objects must be revoked before they can be destroyed.
:param revocation_reason: A
:class:`kmip.core.enums.RevocationReasonCode` enumeration
indicating the revocation reason. See
:term:`revocation_reason_code` for more information.
:param string uid: The unique ID of the managed object to revoke.
Optional, defaults to None.
:param string revocation_message: A message regarding the revocation.
Optional, defaults to None.
:param int compromise_occurrence_date: An integer, the number of
seconds since the epoch, which will be converted to the Datetime
when the managed object was first believed to be compromised.
Optional, defaults to None.
:return: None
:raises kmip.pie.exceptions.ClientConnectionNotOpen: This is raised if
the client connection is unusable.
:raises kmip.pie.exceptions.KmipOperationFailure: This is raised if the
operation result is a failure.
:raises TypeError: This is raised if the input argument is invalid.
Revoking an activated symmetric key would look like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> symmetric_key = objects.SymmetricKey(
... enums.CryptographicAlgorithm.AES,
... 128,
... (
... b'\x00\x01\x02\x03\x04\x05\x06\x07'
... b'\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F'
... )
... )
>>> with c:
... key_id = c.register(symmetric_key)
... c.activate(key_id)
... c.revoke(
... enums.RevocationReasonCode.CESSATION_OF_OPERATION,
... key_id
... )
.. py:method:: destroy(uid=None)
Destroy a managed object stored by a KMIP appliance.
:param string uid: The unique ID of the managed object to destroy.
:return: None
:raises kmip.pie.exceptions.ClientConnectionNotOpen: This is raised if
the client connection is unusable.
:raises kmip.pie.exceptions.KmipOperationFailure: This is raised if the
operation result is a failure.
:raises TypeError: This is raised if the input argument is invalid.
Destroying a symmetric key would look like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> symmetric_key = objects.SymmetricKey(
... enums.CryptographicAlgorithm.AES,
... 128,
... (
... b'\x00\x01\x02\x03\x04\x05\x06\x07'
... b'\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F'
... )
... )
>>> with c:
... key_id = c.register(symmetric_key)
... c.destroy(key_id)
.. py:method:: encrypt(data, uid=None, cryptographic_parameters=None, iv_counter_nonce=None)
Encrypt data using the specified encryption key and parameters.
:param bytes data: The bytes to encrypt. Required.
:param string uid: The unique ID of the encryption key to use.
Optional, defaults to None.
:param dict cryptographic_parameters: A dictionary containing various
cryptographic settings to be used for the encryption. Optional,
defaults to None. See :term:`cryptographic_parameters` for more
information.
:param bytes iv_counter_nonce: The bytes to use for the IV/counter/
nonce, if needed by the encryption algorithm and/or cipher mode.
Optional, defaults to None.
:return: The encrypted data bytes.
:return: The IV/counter/nonce bytes used with the encryption algorithm,
only if it was autogenerated by the server.
:raises kmip.pie.exceptions.ClientConnectionNotOpen: This is raised if
the client connection is unusable.
:raises kmip.pie.exceptions.KmipOperationFailure: This is raised if the
operation result is a failure.
:raises TypeError: This is raised if the input argument is invalid.
Encrypting plain text with a symmetric key would look like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> with c:
... key_id = c.create(
... enums.CryptographicAlgorithm.AES,
... 256,
... cryptographic_usage_mask=[
... enums.CryptographicUsageMask.ENCRYPT,
... enums.CryptographicUsageMask.DECRYPT
... ]
... )
... c.activate(key_id)
... c.encrypt(
... b'This is a secret message.',
... uid=key_id,
... cryptographic_parameters={
... 'cryptographic_algorithm':
... enums.CryptographicAlgorithm.AES,
... 'block_cipher_mode': enums.BlockCipherMode.CBC,
... 'padding_method': enums.PaddingMethod.PKCS5
... },
... iv_counter_nonce=(
... b'\x85\x1e\x87\x64\x77\x6e\x67\x96'
... b'\xaa\xb7\x22\xdb\xb6\x44\xac\xe8'
... )
... )
...
(b'...', None)
.. py:method:: decrypt(data, uid=None, cryptographic_parameters=None, iv_counter_nonce=None)
Decrypt data using the specified decryption key and parameters.
:param bytes data: The bytes to decrypt. Required.
:param string uid: The unique ID of the decryption key to use.
Optional, defaults to None.
:param dict cryptographic_parameters: A dictionary containing various
cryptographic settings to be used for the decryption. Optional,
defaults to None. See :term:`cryptographic_parameters` for more
information.
:param bytes iv_counter_nonce: The bytes to use for the IV/counter/
nonce, if needed by the decryption algorithm and/or cipher mode.
Optional, defaults to None.
:return: The decrypted data bytes.
:raises kmip.pie.exceptions.ClientConnectionNotOpen: This is raised if
the client connection is unusable.
:raises kmip.pie.exceptions.KmipOperationFailure: This is raised if the
operation result is a failure.
:raises TypeError: This is raised if the input argument is invalid.
Decrypting cipher text with a symmetric key would look like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> with c:
... key_id = c.create(
... enums.CryptographicAlgorithm.AES,
... 256,
... cryptographic_usage_mask=[
... enums.CryptographicUsageMask.ENCRYPT,
... enums.CryptographicUsageMask.DECRYPT
... ]
... )
... c.activate(key_id)
... c.decrypt(
... (
... b' \xb6:s0\x16\xea\t\x1b\x16\xed\xb2\x04-\xd6'
... b'\xb6\\\xf3xJ\xfe\xa7[\x1eJ\x08I\xae\x14\xd2'
... b\xdb\xe2'
... ),
... uid=key_id,
... cryptographic_parameters={
... 'cryptographic_algorithm':
... enums.CryptographicAlgorithm.AES,
... 'block_cipher_mode': enums.BlockCipherMode.CBC,
... 'padding_method': enums.PaddingMethod.PKCS5
... },
... iv_counter_nonce=(
... b'\x85\x1e\x87\x64\x77\x6e\x67\x96'
... b'\xaa\xb7\x22\xdb\xb6\x44\xac\xe8'
... )
... )
...
b'This is a secret message.'
.. py:method:: sign(data, uid=None, cryptographic_parameters=None)
Create a digital signature for data using the specified signing key.
:param bytes data: The bytes of the data to be signed. Required.
:param string uid: The unique ID of the signing key to use. Optional,
defaults to None.
:param dict cryptographic_parameters: A dictionary containing various
cryptographic settings to be used for creating the signature (e.g.,
cryptographic algorithm, hashing algorithm, and/or digital
signature algorithm). Optional, defaults to None. See
:term:`cryptographic_parameters` for more information.
:return: Bytes representing the signature of the data.
:raises kmip.pie.exceptions.ClientConnectionNotOpen: This is raised if
the client connection is unusable.
:raises kmip.pie.exceptions.KmipOperationFailure: This is raised if the
operation result is a failure.
:raises TypeError: This is raised if the input argument is invalid.
Signing data with a private key would look like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> with c:
... public_key_id, private_key_id = c.create_key_pair(
... enums.CryptographicAlgorithm.RSA,
... 2048,
... public_usage_mask=[
... enums.CryptographicUsageMask.VERIFY
... ],
... private_usage_mask=[
... enums.CryptographicUsageMask.SIGN
... ]
... )
... c.activate(public_key_id)
... c.activate(private_key_id)
... signature = c.sign(
... b'This is a signed message.',
... uid=private_key_id,
... cryptographic_parameters={
... 'padding_method': enums.PaddingMethod.PSS,
... 'cryptographic_algorithm':
... enums.CryptographicAlgorithm.RSA,
... 'hashing_algorithm': enums.HashingAlgorithm.SHA_256
... }
... )
...
>>> signature
b'...'
.. py:method:: signature_verify(message, signature, uid=None, cryptographic_parameters=None)
Verify a message signature using the specified signing key.
:param bytes message: The bytes of the signed message. Required.
:param bytes signature: The bytes of the message signature. Required.
:param string uid: The unique ID of the signing key to use. Optional,
defaults to None.
:param dict cryptographic_parameters: A dictionary containing various
cryptographic settings to be used for signature verification (e.g.,
cryptographic algorithm, hashing algorithm, and/or digital
signature algorithm). Optional, defaults to None. See
:term:`cryptographic_parameters` for more information.
:return: A :class:`kmip.core.enums.ValidityIndicator` enumeration
indicating whether or not the signature was valid.
:raises kmip.pie.exceptions.ClientConnectionNotOpen: This is raised if
the client connection is unusable.
:raises kmip.pie.exceptions.KmipOperationFailure: This is raised if the
operation result is a failure.
:raises TypeError: This is raised if the input argument is invalid.
Verifying a signature with a public key would look like this:
.. code-block:: python
>>> from kmip.pie import objects
>>> from kmip.pie import client
>>> from kmip import enums
>>> c = client.ProxyKmipClient()
>>> with c:
... public_key_id, private_key_id = c.create_key_pair(
... enums.CryptographicAlgorithm.RSA,
... 2048,
... public_usage_mask=[
... enums.CryptographicUsageMask.VERIFY
... ],
... private_usage_mask=[
... enums.CryptographicUsageMask.SIGN
... ]
... )
... c.activate(public_key_id)
... c.activate(private_key_id)
... c.signature_verify(
... b'This is a signed message.',
... b'...',
... uid=public_key_id,
... cryptographic_parameters={
... 'padding_method': enums.PaddingMethod.PSS,
... 'cryptographic_algorithm':
... enums.CryptographicAlgorithm.RSA,
... 'hashing_algorithm': enums.HashingAlgorithm.SHA_256
... }
... )
...
<ValidityIndicator.VALID: 1>
.. py:method:: mac(data, uid=None, algorithm=None)
Documentation coming soon.

11
docs/source/community.rst Normal file
View File

@ -0,0 +1,11 @@
Community
=========
The PyKMIP community has various forums and resources you can use:
* `Source code`_
* `Issue tracker`_
* IRC: ``#pykmip`` on ``irc.freenode.net``
* Twitter: ``@pykmip``
.. _`Source code`: https://github.com/openkmip/pykmip
.. _`Issue tracker`: https://github.com/openkmip/pykmip/issues

174
docs/source/conf.py Normal file
View File

@ -0,0 +1,174 @@
# -*- coding: utf-8 -*-
#
# PyKMIP documentation build configuration file, created by
# sphinx-quickstart on Tue Oct 10 16:02:35 2017.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
import sphinx_rtd_theme
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'PyKMIP'
copyright = u'2017, Peter Hamilton'
author = u'Peter Hamilton'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'0.8'
# The full version, including alpha/beta/rc tags.
release = u'0.8.dev'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
#html_theme = 'alabaster'
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# This is required for the alabaster theme
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
html_sidebars = {
'**': [
'about.html',
'navigation.html',
'relations.html', # needs 'show_related': True theme option to display
'searchbox.html',
'donate.html',
]
}
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'PyKMIPdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'PyKMIP.tex', u'PyKMIP Documentation',
u'Peter Hamilton', 'manual'),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'pykmip', u'PyKMIP Documentation',
[author], 1)
]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'PyKMIP', u'PyKMIP Documentation',
author, 'PyKMIP', 'One line description of project.',
'Miscellaneous'),
]

123
docs/source/development.rst Normal file
View File

@ -0,0 +1,123 @@
Development
===========
Development for PyKMIP is open to all contributors. Use the information
provided here to inform your contributions and help the project maintainers
review and accept your work.
Getting Started
---------------
File a new issue on the project `issue tracker`_ on GitHub describing the
work you intend on doing. This is especially recommended for any sizable
contributions, like adding support for a new KMIP operation or adding a new
cryptographic backend for the server. Provide as much information on your
feature request as possible, using information from the KMIP specifications
or existing feature support in PyKMIP where applicable.
The issue number for your new issue should be included at the end of the
commit message of each patch related to that issue.
If you simply want to request a new feature but do not intend on working on
it, file your issue as normal and the project maintainers will triage it for
future work.
.. _writing-code:
Writing Code
------------
New code should be written in its own Git branch, ideally branched from
``HEAD`` on ``master``. If other commits are merged into ``master`` after your
branch was created, be sure to rebase your work on the current state of
``master`` before submitting a pull request to GitHub.
New code should generally follow ``PEP 8`` style guidelines, though there are
exceptions that will be allowed in special cases. Run the ``flake8`` tests to
check your code before submitting a pull request (see :ref:`running-tests`).
Commit Messages
---------------
Commit messages should include a single line title (75 character max) followed
by a blank line and a description of the change, including feature details,
testing and documentation updates, feature limitations, known issues, etc.
The issue number for the issue associated with the commit should be included
at the end of the commit message, if it exists. If the commit is the final one
for a specific issue, use ``Closes #XXX`` or ``Fixes #XXX`` to link the issue
and close it simultaneously. For example, see ths commit for `Issue #312`_:
.. code-block:: console
Fix bug generating detached instance errors in server tests
This patch fixes a bug that generates intermittent sqlalchemy
DetachedInstanceErrors during the KMIP server engine unit test
execution. Specifically, this fix disables instance expiration on
commit for the sqlalchemy sessions used throughout the unit tests,
allowing access to instance attributes even if the instance is
detached from a session.
Fixes #312
Bug Fixes
---------
If you have found a bug in PyKMIP, file a new issue and use the title format
``Bug: <brief description here>``. In the body of the issue please provide as
much information as you can, including Python version, PyKMIP version,
operating system version, and any stacktraces or logging information produced
by PyKMIP related to the bug. See `What to put in your bug report`_ for a
breakdown of bug reporting best practices.
If you are working on a bug fix for a bug in ``master``, follow the general
guidelines above for branching and code development (see :ref:`writing-code`).
If you are working on a bug fix for an older version of PyKMIP, your branch
should be based on the latest commit of the repository branch for the version
of PyKMIP the bug applies to (e.g., branch ``release-0.6.0`` for PyKMIP 0.6).
The pull request for your bug fix should also target the version branch in
question. If applicable, it will be pulled forward to newer versions of
PyKMIP, up to and including ``master``.
.. _running-tests:
Running Tests
-------------
PyKMIP uses ``tox`` to manage testing across multiple Python versions. Test
infrastructure currently supports Python 2.7, 3.3, 3.4, 3.5, and 3.6. Test
coverage results are currently included with each Python test environment. To
test against a specific Python version (e.g., Python 2.7), run:
.. code-block:: console
$ tox -e py27
PyKMIP also provides ``tox`` environments for style and security checks.
The style checks leverage ``flake8`` and can be run like so:
.. code-block:: console
$ tox -e pep8
The security checks use ``bandit`` and can be run like so:
.. code-block:: console
$ tox -e bandit
To run the entire testing suite, simply run ``tox`` without any arguments:
.. code-block:: console
$ tox
For more information on the testing tools used here, see the following
resources:
* `tox`_
* `flake8`_
* `bandit`_
.. _`issue tracker`: https://github.com/OpenKMIP/PyKMIP/issues
.. _`Issue #312`: https://github.com/OpenKMIP/PyKMIP/issues/312
.. _`What to put in your bug report`: http://www.contribution-guide.org/#what-to-put-in-your-bug-report
.. _`tox`: https://pypi.python.org/pypi/tox
.. _`flake8`: https://pypi.python.org/pypi/flake8
.. _`bandit`: https://pypi.python.org/pypi/bandit

334
docs/source/faq.rst Normal file
View File

@ -0,0 +1,334 @@
Frequently Asked Questions
==========================
.. contents:: Table of Contents
What algorithms are available for creating symmetric encryption keys? For asymmetric encryption keys (i.e., key pairs)?
-----------------------------------------------------------------------------------------------------------------------
The KMIP specification supports a wide variety of symmetric and asymmetric
key algorithms. Support for these algorithms, including corresponding key
lengths, will vary across different KMIP-compliant devices, so check with
your KMIP vendor or with your appliance documentation to determine which
ones are available.
For a full list of the cryptographic algorithms supported by the KMIP
specification, see :term:`cryptographic_algorithm`. The following algorithms
are supported by the PyKMIP server.
Symmetric Key Algorithms
~~~~~~~~~~~~~~~~~~~~~~~~
* `3DES`_
* `AES`_
* `Blowfish`_
* `Camellia`_
* `CAST5`_
* `IDEA`_
* `RC4`_
Asymmetric Key Algorithms
~~~~~~~~~~~~~~~~~~~~~~~~~
* `RSA`_
How does the PyKMIP server handle client identity and authentication?
---------------------------------------------------------------------
Client authentication for the PyKMIP server is currently enforced by the
validation of the client certificate used to establish the client/server
TLS connection. If the client connects to the server with a certificate
that has been signed by a certificate authority recognized by the server,
the connection is allowed. If the server cannot validate the client's
certificate, the connection is blocked and the client cannot access any
objects stored on the server.
If client authentication succeeds, the identity of the client is obtained
from the client's certificate. The server will extract the common name from
the certificate's subject distinguished name and use the common name as the
identity of the client. If the ``enable_tls_client_auth`` configuration
setting is set to ``True``, the server will check the client's certificate
for the extended key usage extension (see `RFC 5280`_). In this case the
certificate must have the extension marked for client authentication, which
indicates that the certificate can be used to derive client identity. If
the extension is not present or is marked incorrectly, the server will not
be able to derive the client's identity and will close the connection. If
the ``enable_tls_client_auth`` configuration setting is set to ``False``,
the certificate extension check is omitted.
Once the client's identity is obtained, the client's request is processed. Any
objects created or registered by the client will be marked as owned by the
client identity. This identity is then used in conjunction with KMIP operation
policies to enforce object access control (see the next question for more
information).
How does the PyKMIP server manage access control for the keys and objects it stores?
------------------------------------------------------------------------------------
Access control for server objects is managed through KMIP operation policies.
An operation policy is a set of permissions, indexed by object type and
operation. For any KMIP object type and operation pair, the policy defines
who is allowed to conduct the operation on the object type.
There are three basic permissions currently supported by KMIP: Allow All,
Allow Owner, and Disallow All. An object type/operation pair mapped to the
Allow All permission indicates that any client authenticated with the server
can conduct the corresponding operation on any object of the corresponding
type. The Allow Owner permission restricts the operation to any client
authenticated and identified as the owner of the object. The Disallow All
permission blocks any client from conducting the operation on the object and
is usually reserved for static public objects or tasks that only the server
itself is allowed to perform.
For example, let's examine a simple use case where a client wants to retrieve
a symmetric key from the server. The client submits a Get request to the
server, including the UUID of the symmetric key it wants to retrieve. The
server will derive the client's identity and then lookup the object with the
corresponding UUID. If the object is located, the server will check the
object's operation policy attribute for the name of the operation policy
associated with the object. The server will then use the operation policy, the
client's identity, the object's type, the object's owner, and the operation to
determine if the client can retrieve the symmetric key. If the operation
policy has symmetric keys and the Get operation mapped to Allow All, the
operation is allowed for the client regardless of the client's identity and
the symmetric key is returned to the client. If the permission is set to Allow
Owner, the server will return the symmetric key only if the client's identity
matches the object's owner. If the permission is set to Disallow All, the
server will refuse to return the symmetric key, regardless of the client's
identity.
While an operation policy can cover every possible combination of object type
and operation, it does not have to. If a policy does not cover a specific
object type or operation, the server defaults to the safest option and acts
as if the permission was set to Disallow All.
Each KMIP object is assigned an operation policy and owner upon creation. If
no operation policy is included in the creation request, the server
automatically assigns it the ``default`` operation policy. The ``default``
operation policy is defined in the KMIP specification and is built-in to the
PyKMIP server; it cannot be redefined or overridden by the user or server
administrator (see the next question for details on built-in operation
policies).
In addition to the built-in operation policies, the PyKMIP server does allow
users to define their own operation policies. An example policy file,
``policy.json``, is included in the ``examples`` directory of the PyKMIP
repository. Let's take a look at the first few lines from the policy:
.. code-block:: json
{
"example": {
"CERTIFICATE": {
"LOCATE": "ALLOW_ALL",
"CHECK": "ALLOW_ALL",
}
}
}
The first piece of information in the policy file is the name of the policy,
in this case ``example``. The name maps to a set of object types, which in
turn are mapped to a set of operations with associated permissions. In the
snippet above, the first object type supported is ``CERTIFICATE`` followed by
two supported operations, ``LOCATE`` and ``CHECK``. Both operations are mapped
to the ``ALLOW_ALL`` permission. Putting this all together, for the ``example``
policy certificate objects used with the ``Locate`` or ``Check`` operations are
allowed for all clients, regardless of who owns the certificate being accessed.
If you examine the full example file, you will see more operations listed,
along with additional object types.
In general, a policy file is a basic JSON file that links a name for the policy
to a table of object type/operation pairs that each map to one of the
permissions defined above. Users can copy this policy file and edit it to
create their own policies. Once the policy is ready, the server administrator
can place it in the server's policy directory and restart the server to load
in the new policy. The server administrator can configure which directory
should act as the server's policy directory by setting the ``policy_path``
configuration option in the server's ``server.conf`` file. Note that it is up
to the server administrator to ensure that user-defined policies do not
overwrite each other by using identical policy names.
What built-in operation policies does the PyKMIP server support?
----------------------------------------------------------------
The PyKMIP server defines two built-in operation policies: ``default`` and
``public``. Both of these policies are defined in the KMIP specification and
each is a reserved policy; neither can be renamed or overridden by
user-defined policies. The ``default`` policy is used for newly created objects
that are not assigned a policy by their creators, though it can be used by
creators intentionally. The ``public`` policy is intended for use with template
objects that are public to the entire user-base of the server.
The following tables define the permissions for each of the built-in policies.
``default`` policy
~~~~~~~~~~~~~~~~~~
============= ==================== ============
Object Type Operation Permission
============= ==================== ============
Certificate Locate Allow All
Certificate Check Allow All
Certificate Get Allow All
Certificate Get Attributes Allow All
Certificate Get Attribute List Allow All
Certificate Add Attribute Allow Owner
Certificate Modify Attribute Allow Owner
Certificate Delete Attribute Allow Owner
Certificate Obtain Lease Allow All
Certificate Activate Allow Owner
Certificate Revoke Allow Owner
Certificate Destroy Allow Owner
Certificate Archive Allow Owner
Certificate Recover Allow Owner
Symmetric Key Rekey Allow Owner
Symmetric Key Rekey Key Pair Allow Owner
Symmetric Key Derive Key Allow Owner
Symmetric Key Locate Allow Owner
Symmetric Key Check Allow Owner
Symmetric Key Get Allow Owner
Symmetric Key Get Attributes Allow Owner
Symmetric Key Get Attribute List Allow Owner
Symmetric Key Add Attribute Allow Owner
Symmetric Key Modify Attribute Allow Owner
Symmetric Key Delete Attribute Allow Owner
Symmetric Key Obtain Lease Allow Owner
Symmetric Key Get Usage Allocation Allow Owner
Symmetric Key Activate Allow Owner
Symmetric Key Revoke Allow Owner
Symmetric Key Destroy Allow Owner
Symmetric Key Archive Allow Owner
Symmetric Key Recover Allow Owner
Public Key Locate Allow All
Public Key Check Allow All
Public Key Get Allow All
Public Key Get Attributes Allow All
Public Key Get Attribute List Allow All
Public Key Add Attribute Allow Owner
Public Key Modify Attribute Allow Owner
Public Key Delete Attribute Allow Owner
Public Key Obtain Lease Allow All
Public Key Activate Allow Owner
Public Key Revoke Allow Owner
Public Key Destroy Allow Owner
Public Key Archive Allow Owner
Public Key Recover Allow Owner
Private Key Rekey Allow Owner
Private Key Rekey Key Pair Allow Owner
Private Key Derive Key Allow Owner
Private Key Locate Allow Owner
Private Key Check Allow Owner
Private Key Get Allow Owner
Private Key Get Attributes Allow Owner
Private Key Get Attribute List Allow Owner
Private Key Add Attribute Allow Owner
Private Key Modify Attribute Allow Owner
Private Key Delete Attribute Allow Owner
Private Key Obtain Lease Allow Owner
Private Key Get Usage Allocation Allow Owner
Private Key Activate Allow Owner
Private Key Revoke Allow Owner
Private Key Destroy Allow Owner
Private Key Archive Allow Owner
Private Key Recover Allow Owner
Split Key Rekey Allow Owner
Split Key Rekey Key Pair Allow Owner
Split Key Derive Key Allow Owner
Split Key Locate Allow Owner
Split Key Check Allow Owner
Split Key Get Allow Owner
Split Key Get Attributes Allow Owner
Split Key Get Attribute List Allow Owner
Split Key Add Attribute Allow Owner
Split Key Modify Attribute Allow Owner
Split Key Delete Attribute Allow Owner
Split Key Obtain Lease Allow Owner
Split Key Get Usage Allocation Allow Owner
Split Key Activate Allow Owner
Split Key Revoke Allow Owner
Split Key Destroy Allow Owner
Split Key Archive Allow Owner
Split Key Recover Allow Owner
Template Locate Allow Owner
Template Get Allow Owner
Template Get Attributes Allow Owner
Template Get Attribute List Allow Owner
Template Add Attribute Allow Owner
Template Modify Attribute Allow Owner
Template Delete Attribute Allow Owner
Template Destroy Allow Owner
Secret Data Rekey Allow Owner
Secret Data Rekey Key Pair Allow Owner
Secret Data Derive Key Allow Owner
Secret Data Locate Allow Owner
Secret Data Check Allow Owner
Secret Data Get Allow Owner
Secret Data Get Attributes Allow Owner
Secret Data Get Attribute List Allow Owner
Secret Data Add Attribute Allow Owner
Secret Data Modify Allow Owner
Secret Data Delete Attribute Allow Owner
Secret Data Obtain Lease Allow Owner
Secret Data Get Usage Allocation Allow Owner
Secret Data Activate Allow Owner
Secret Data Revoke Allow Owner
Secret Data Destroy Allow Owner
Secret Data Archive Allow Owner
Secret Data Recover Allow Owner
Opaque Data Rekey Allow Owner
Opaque Data Rekey Key Pair Allow Owner
Opaque Data Derive Key Allow Owner
Opaque Data Locate Allow Owner
Opaque Data Check Allow Owner
Opaque Data Get Allow Owner
Opaque Data Get Attributes Allow Owner
Opaque Data Get Attribute List Allow Owner
Opaque Data Add Attribute Allow Owner
Opaque Data Modify Attribute Allow Owner
Opaque Data Delete Attribute Allow Owner
Opaque Data Obtain Lease Allow Owner
Opaque Data Get Usage Allocation Allow Owner
Opaque Data Activate Allow Owner
Opaque Data Revoke Allow Owner
Opaque Data Destroy Allow Owner
Opaque Data Archive Allow Owner
Opaque Data Recover Allow Owner
PGP Key Rekey Allow Owner
PGP Key Rekey Key Pair Allow Owner
PGP Key Derive Key Allow Owner
PGP Key Locate Allow Owner
PGP Key Check Allow Owner
PGP Key Get Allow Owner
PGP Key Get Attributes Allow Owner
PGP Key Get Attribute List Allow Owner
PGP Key Add Attribute Allow Owner
PGP Key Modify Attribute Allow Owner
PGP Key Delete Attribute Allow Owner
PGP Key Obtain Lease Allow Owner
PGP Key Get Usage Allocation Allow Owner
PGP Key Activate Allow Owner
PGP Key Revoke Allow Owner
PGP Key Destroy Allow Owner
PGP Key Archive Allow Owner
PGP Key Recover Allow Owner
============= ==================== ============
``public`` policy
~~~~~~~~~~~~~~~~~
=========== ================== ============
Object Type Operation Permission
=========== ================== ============
Template Locate Allow All
Template Get Allow All
Template Get Attributes Allow All
Template Get Attribute List Allow All
Template Add Attribute Disallow All
Template Modify Attribute Disallow All
Template Delete Attribute Disallow All
Template Destroy Disallow All
=========== ================== ============
.. |check| unicode:: U+2713
.. _`3DES`: https://en.wikipedia.org/wiki/Triple_DES
.. _`AES`: https://en.wikipedia.org/wiki/Advanced_Encryption_Standard
.. _`Blowfish`: https://en.wikipedia.org/wiki/Blowfish_%28cipher%29
.. _`Camellia`: https://en.wikipedia.org/wiki/Camellia_%28cipher%29
.. _`CAST5`: https://en.wikipedia.org/wiki/CAST-128
.. _`IDEA`: https://en.wikipedia.org/wiki/International_Data_Encryption_Algorithm
.. _`RC4`: https://en.wikipedia.org/wiki/RC4
.. _`RSA`: https://en.wikipedia.org/wiki/RSA_%28cryptosystem%29
.. _`RFC 5280`: https://www.ietf.org/rfc/rfc5280.txt

1651
docs/source/glossary.rst Normal file
View File

File diff suppressed because it is too large Load Diff

51
docs/source/index.rst Normal file
View File

@ -0,0 +1,51 @@
Welcome to PyKMIP
=================
PyKMIP is a Python implementation of the Key Management Interoperability
Protocol (KMIP), an `OASIS`_ communication standard for the management of
objects stored and maintained by key management systems. KMIP defines how key
management operations and operation data should be encoded and communicated
between client and server applications. Supported operations include the full
`CRUD`_ key management lifecycle, including operations for managing object
metadata and for conducting cryptographic operations. Supported object types
include:
* symmetric/asymmetric encryption keys
* passwords/passphrases
* certificates
* opaque data blobs, and more
For more information on KMIP, check out the `OASIS KMIP Technical Committee`_
and the `OASIS KMIP Documentation`_.
Installation
------------
You can install PyKMIP via ``pip``:
.. code-block:: console
$ pip install pykmip
See :doc:`Installation <installation>` for more information.
Layout
------
PyKMIP provides both client and server functionality, allowing developers
to incorporate the full key management lifecycle into their projects. For
more information, check out the various articles below.
.. toctree::
:maxdepth: 2
installation
changelog
faq
development
client
server
community
glossary
.. _`CRUD`: https://en.wikipedia.org/wiki/Create,_read,_update_and_delete
.. _`OASIS`: https://www.oasis-open.org
.. _`OASIS KMIP Technical Committee`: https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=kmip
.. _`OASIS KMIP Documentation`: https://docs.oasis-open.org/kmip/spec/

38
docs/source/installation.rst Normal file
View File

@ -0,0 +1,38 @@
Installation
============
You can install PyKMIP via ``pip``:
.. code-block:: console
$ pip install pykmip
Supported platforms
-------------------
PyKMIP is tested on Python 2.7, 3.3, 3.4, 3.5, and 3.6 on the following
operating systems:
* Ubuntu 12.04, 14.04, and 16.04
PyKMIP also works on Windows and MacOSX however these platforms are not
officially supported or tested.
Building PyKMIP on Linux
------------------------
You can install PyKMIP from source via ``git``:
.. code-block:: console
$ git clone https://github.com/openkmip/pykmip.git
$ python pykmip/setup.py install
If you are on a fresh Linux build, you may also need several additional system
dependencies, including headers for Python, OpenSSL, ``libffi``, and
``libsqlite3``.
Ubuntu
~~~~~~
Replace ``python-dev`` with ``python3-dev`` if you are using Python 3.0+.
.. code-block:: console
$ sudo apt-get install python-dev libff-dev libssl-dev libsqlite3-dev

742
docs/source/server.rst Normal file
View File

@ -0,0 +1,742 @@
Server
======
.. warning::
The PyKMIP server is intended for testing and demonstration purposes only.
It is **not** a replacement for a secure, hardened, hardware-based key
management appliance. It should **not** be used in a production-level
environment, nor for critical operations.
The PyKMIP server is a software implementation of a KMIP-compliant key
management appliance. It supports over a dozen key management operations,
including key lifecycle management, object metadata access, and cryptographic
functions like encrypting and signing data.
The server is used to test the functionality of the PyKMIP client and library
and is primarily intended as a testing and demonstration tool.
Configuration
-------------
The server settings can be managed by a configuration file, by default located
at ``/etc/pykmip/server.conf``. An example server configuration settings block,
as found in the configuration file, is shown below:
.. code-block:: console
[server]
hostname=127.0.0.1
port=5696
certificate_path=/path/to/certificate/file
key_path=/path/to/certificate/key/file
ca_path=/path/to/ca/certificate/file
auth_suite=Basic
policy_path=/path/to/policy/file
enable_tls_client_auth=True
tls_cipher_suites=
TLS_RSA_WITH_AES_128_CBC_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
logging_level=DEBUG
The server can also be configured manually via Python. The following example
shows how to create the ``KmipServer`` in Python code, directly specifying the
different configuration values:
.. code-block:: python
>>> from kmip.services.server import KmipServer
>>> server = KmipServer(
... hostname='127.0.0.1',
... port=5696,
... certificate_path='/path/to/certificate/file/',
... key_path='/path/to/certificate/key/file/',
... ca_path='/path/to/ca/certificate/file/',
... auth_suite='Basic',
... config_path='/etc/pykmip/server.conf',
... log_path='/var/log/pykmip/server.log',
... policy_path='/etc/pykmip/policies',
... enable_tls_client_auth=True,
... tls_cipher_suites=[
... 'TLS_RSA_WITH_AES_128_CBC_SHA256',
... 'TLS_RSA_WITH_AES_256_CBC_SHA256',
... 'TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384'
... ],
... logging_level='DEBUG'
... )
The different configuration options are defined below:
* ``hostname``
A string representing either a hostname in Internet domain notation or an
IPv4 address.
* ``port``
An integer representing a port number. Recommended to be ``5696``
according to the KMIP specification.
* ``certificate_path``
A string representing a path to a PEM-encoded server certificate file. For
more information, see the `ssl`_ documentation.
* ``key_path``
A string representing a path to a PEM-encoded server certificate key file.
The private key contained in the file must correspond to the certificate
pointed to by ``certificate_path``. For more information, see the `ssl`_
documentation.
* ``ca_path``
A string representing a path to a PEM-encoded certificate authority
certificate file. If using a self-signed certificate, the ``ca_path`` and
the ``certificate_path`` should be identical. For more information, see
the `ssl`_ documentation.
* ``auth_suite``
A string representing the type of authentication suite to use when
establishing TLS connections. Acceptable values are ``Basic`` and
``TLS1.2``.
.. note::
``TLS1.2`` can only be used with versions of Python that support
TLS 1.2 (e.g,. Python 2.7.9+ or Python 3.4+). If you are running on an
older version of Python, you will only be able to use basic TLS 1.0
authentication. For more information, see the `ssl`_ documentation.
* ``config_path``
A string representing a path to a server configuration file, as shown
above. Only set via the ``KmipServer`` constructor. Defaults to
``/etc/pykmip/server.conf``.
* ``log_path``
A string representing a path to a log file. The server will set up a
rotating file logger on this file. Only set via the ``KmipServer``
constructor. Defaults to ``/var/log/pykmip/server.log``.
* ``policy_path``
A string representing a path to the filesystem directory containing
PyKMIP server operation policy JSON files.
* ``enable_tls_client_auth``
A boolean indicating whether or not extension checks should be performed
on client certificates to verify that they can be used to derive client
identity. This setting is enabled by default for backwards compatibility
and must be explicitly disabled if this behavior is not desired.
* ``tls_cipher_suites``
A list of strings representing the set of cipher suites to use when
establishing TLS connections with new clients. Enable debug logging for
more information on the cipher suites used by the client and server.
* ``logging_level``
A string indicating what the base logging level should be for the server.
Options include: DEBUG, INFO, WARNING, ERROR, and CRITICAL. The DEBUG
log level logs the most information, the CRITICAL log level logs the
least.
.. note::
When installing PyKMIP and deploying the server, you must manually set up
the server configuration file. It **will not** be placed in ``/etc/pykmip``
automatically. See ``/examples`` in the PyKMIP repository for a boilerplate
configuration file to get started.
Usage
-----
The software server can be run using the ``bin/run_server.py`` startup script.
If you are currently in the PyKMIP root directory, use the following command:
.. code-block:: console
$ python bin/run_server.py
If you need more information about running the startup script, pass ``-h``
to it:
.. code-block: console
$ python bin/run_server.py -h
.. note::
You may need to run the server as root, depending on the permissions of the
configuration, log, and certificate file directories.
If PyKMIP is installed and you are able to ``import kmip`` in Python, you can
copy the startup script and run it from any directory you choose.
Storage
-------
All data storage for the server is managed via `sqlalchemy`_. The current
backend leverages `SQLite`_, storing managed objects in a flat file located
at ``/tmp/pykmip.database``. If this file is deleted, the stored objects will
be gone for good. If this file is preserved across server restarts, object
access will be maintained.
.. note::
Updates to the server data model will generate errors if the server is
run with a ``pykmip.database`` file adhering to an older data model. There
is no upgrade path.
Long term, the intent is to add support for more robust database and storage
backends available through ``sqlalchemy``. If you are interested in this work,
please see :doc:`Development <development>` for more information.
.. _objects:
Objects
-------
The following is a list of KMIP managed object types supported by the server.
Symmetric Keys
~~~~~~~~~~~~~~
A symmetric key is an encryption key that can be used to both encrypt plain
text data and decrypt cipher text.
Creating a symmetric key object would look like this:
.. code-block:: python
>>> from kmip import enums
>>> from kmip.pie.objects import SymmetricKey
>>> key = SymmetricKey(
... enums.CryptographicAlgorithm.AES,
... 128,
... (
... b'\x00\x01\x02\x03\x04\x05\x06\x07'
... b'\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F'
... ),
... [
... enums.CryptographicUsageMask.ENCRYPT,
... enums.CryptographicUsageMask.DECRYPT
... ],
... "Example Symmetric Key"
... )
Public Keys
~~~~~~~~~~~
A public key is a cryptographic key that contains the public components of an
asymmetric key pair. It is often used to decrypt data encrypted with, or to
verify signatures produced by, the corresponding private key.
Creating a public key object would look like this:
.. code-block:: python
>>> from kmip import enums
>>> from kmip.pie.objects import PublicKey
>>> key = PublicKey(
... enums.CryptographicAlgorithm.RSA,
... 2048,
... (
... b'\x30\x82\x01\x0A\x02\x82\x01\x01...'
... ),
... enums.KeyFormatType.X_509,
... [
... enums.CryptographicUsageMask.VERIFY
... ],
... "Example Public Key"
... )
Private Keys
~~~~~~~~~~~~
A private key is a cryptographic key that contains the private components of
an asymmetric key pair. It is often used to encrypt data that may be decrypted
by, or generate signatures that may be verified by, the corresponding public
key.
Creating a private key object would look like this:
.. code-block:: python
>>> from kmip import enums
>>> from kmip.pie.objects import PrivateKey
>>> key = PrivateKey(
... enums.CryptographicAlgorithm.RSA,
... 2048,
... (
... b'\x30\x82\x04\xA5\x02\x01\x00\x02...'
... ),
... enums.KeyFormatType.PKCS_8,
... [
... enums.CryptographicUsageMask.SIGN
... ],
... "Example Private Key"
... )
Certificates
~~~~~~~~~~~~
A certificate is a cryptographic object that contains a public key along with
additional identifying information. It is often used to secure communication
channels or to verify data signatures produced by the corresponding private
key.
Creating a certificate object would look like this:
.. code-block:: python
>>> from kmip import enums
>>> from kmip.pie.objects import X509Certificate
>>> cert = X509Certificate(
... (
... b'\x30\x82\x03\x12\x30\x82\x01\xFA...'
... ),
... [
... enums.CryptographicUsageMask.VERIFY
... ],
... "Example X.509 Certificate"
... )
Secret Data
~~~~~~~~~~~
A secret data object is a cryptographic object that represents a shared secret
value that is not a key or certificate (e.g., a password or passphrase).
Creating a secret data object would look like this:
.. code-block:: python
>>> from kmip import enums
>>> from kmip.pie.objects import SecretData
>>> data = SecretData(
... (
... b'\x53\x65\x63\x72\x65\x74\x50\x61'
... b'\x73\x73\x77\x6F\x72\x64'
... ),
... enums.SecretDataType.PASSWORD,
... [
... enums.CryptographicUsageMask.DERIVE_KEY
... ],
... "Example Secret Data Object"
... )
Opaque Objects
~~~~~~~~~~~~~~
An opaque data object is a binary blob that the server is unable to interpret
into another well-defined object type. It can be used to store any arbitrary
data.
Creating an opaque object would look like this:
.. code-block:: python
>>> from kmip import enums
>>> from kmip.pie.objects import OpaqueObject
>>> oo = OpaqueObject(
... (
... b'\x53\x65\x63\x72\x65\x74\x50\x61'
... b'\x73\x73\x77\x6F\x72\x64'
... ),
... enums.OpaqueDataType.NONE,
... "Example Opaque Object"
... )
Operations
----------
The following is a list of KMIP operations supported by the server. All
supported cryptographic functions are currently implemented using the
`pyca/cryptography`_ library, which in turn leverages `OpenSSL`_. If the
underlying backend does not support a specific feature, algorithm, or
operation, the PyKMIP server will not be able to support it either.
If you are interested in adding a new cryptographic backend to the PyKMIP
server, see :doc:`Development <development>` for more information.
Create
~~~~~~
The Create operation is used to create symmetric keys for a variety of
cryptographic algorithms.
========== =======================
Algorithm Key Sizes
========== =======================
3DES 64, 128, 192
AES 128, 256, 192
Blowfish 128, 256, 384, and more
Camellia 128, 256, 192
CAST5 64, 96, 128, and more
IDEA 128
ARC4 128, 256, 192, and more
========== =======================
All users are allowed to create symmetric keys. There are no quotas currently
enforced by the server.
Various KMIP-defined attributes are set when a symmetric key is created.
These include:
* :term:`cryptographic_algorithm`
* :term:`cryptographic_length`
* :term:`cryptographic_usage_mask`
* :term:`initial_date`
* :term:`key_format_type`
* :term:`name`
* :term:`object_type`
* :term:`operation_policy_name`
* :term:`state`
* :term:`unique_identifier`
Errors may be generated during the creation of a symmetric key. These may
occur in the following cases:
* the cryptographic algorithm, length, and/or usage mask are not provided
* an unsupported symmetric algorithm is requested
* an invalid cryptographic length is provided for a specific cryptographic
algorithm
CreateKeyPair
~~~~~~~~~~~~~
The CreateKeyPair operation is used to create asymmetric key pairs.
========== ==========
Algorithm Key Sizes
========== ==========
RSA 1024, 2048
========== ==========
All users are allowed to create asymmetric keys. There are no quotas currently
enforced by the server.
Various KMIP-defined attributes are set when an asymmetric key pair is
created. For both public and private keys, the following attributes are
identical:
* :term:`cryptographic_algorithm`
* :term:`cryptographic_length`
* :term:`initial_date`
* :term:`operation_policy_name`
* :term:`state`
Other attributes will differ between public and private keys. These include:
* :term:`cryptographic_usage_mask`
* :term:`key_format_type`
* :term:`name`
* :term:`object_type`
* :term:`unique_identifier`
Errors may be generated during the creation of an asymmetric key pair. These
may occur in the following cases:
* the cryptographic algorithm, length, and/or usage mask are not provided
* an unsupported asymmetric algorithm is requested
* an invalid cryptographic length is provided for a specific cryptographic
algorithm
Register
~~~~~~~~
The Register operation is used to store an existing KMIP object with the
server. For examples of the objects that can be stored, see :ref:`objects`.
All users are allowed to register objects. There are no quotas currently
enforced by the server.
Various KMIP-defined attributes may be set when an object is registered.
These may include:
* :term:`cryptographic_algorithm`
* :term:`cryptographic_length`
* :term:`cryptographic_usage_mask`
* :term:`initial_date`
* :term:`key_format_type`
* :term:`name`
* :term:`object_type`
* :term:`operation_policy_name`
* :term:`state`
* :term:`unique_identifier`
DeriveKey
~~~~~~~~~
The DeriveKey operation is used to create a new symmetric key or secret data
object from an existing managed object stored on the server. The derivation
method and the desired length of the new cryptographic object must be
specified with the request. If the generated cryptographic object is longer
than the requested length, it will be truncated to match the request length.
Various KMIP-defined attributes are set when a new cryptographic object is
derived. These include:
* :term:`cryptographic_algorithm`
* :term:`cryptographic_length`
* :term:`cryptographic_usage_mask`
* :term:`initial_date`
* :term:`key_format_type`
* :term:`name`
* :term:`object_type`
* :term:`operation_policy_name`
* :term:`state`
* :term:`unique_identifier`
Errors may be generated during the key derivation process. These may occur
in the following cases:
* the base object is not accessible to the user
* the base object is not an object type usable for key derivation
* the base object does not have the DeriveKey bit set in its usage mask
* the cryptographic length is not provided with the request
* the requested cryptographic length is longer than the generated key
Locate
~~~~~~
The Locate operation is used to identify managed objects that the user has
access to, according to specific filtering criteria. Currently, the server
only support object filtering based on the object :term:`name` attribute.
If no filtering values are provided, the server will return a list of
:term:`unique_identifier` values corresponding to all of the managed objects
the user has access to.
Get
~~~
The Get attribute is used to retrieve a managed object stored on the server.
The :term:`unique_identifier` of the object is used to retrieve it.
It is possible to request that the managed object be cryptographically
wrapped before it is returned to the client. Right now only encryption-based
wrapping is supported.
Errors may be generated during the retrieval of a managed object. These
may occur in the following cases:
* the managed object is not accessible to the user
* a desired key format was specified that cannot be converted by the server
* key compression was specified and the server cannot compress objects
* the wrapping key specified is not accessible to the user
* the wrapping key is not applicable to key wrapping
* the wrapping key does not have the WrapKey bit set in its usage mask
* wrapped attributes were specified and the server cannot wrap attributes
* a wrapping encoding was specified and the server does not support it
* incomplete wrapping specifications were provided with the request
GetAttributes
~~~~~~~~~~~~~
The GetAttributes operation is used to retrieve specific attributes for a
specified managed object. Multiple attribute names can be specified in a
single request.
The following names should be used to access the corresponding attributes:
======================== ================================
Attribute Name Attribute
======================== ================================
Cryptographic Algorithm :term:`cryptographic_algorithm`
Cryptographic Length :term:`cryptographic_length`
Cryptographic Usage Mask :term:`cryptographic_usage_mask`
Initial Date :term:`initial_date`
Object Type :term:`object_type`
Operation Policy Name :term:`operation_policy_name`
State :term:`state`
Unique Identifier :term:`unique_identifier`
======================== ================================
GetAttributeList
~~~~~~~~~~~~~~~~
The GetAttributeList operation is used to identify the attributes currently
available for a specific managed object. Given the :term:`unique_identifier`
of a managed object, the server will return a list of attribute names for
attributes that can be accessed using the GetAttributes operation.
Activate
~~~~~~~~
The Activate operation updates the state of a managed object, allowing it to
be used for cryptographic operations. Specifically, the object transitions
from the pre-active state to the active state (see :term:`state`).
Errors may be generated during the activation of a managed object. These
may occur in the following cases:
* the managed object is not activatable (e.g., opaque data object)
* the managed object is not in the pre-active state
Revoke
~~~~~~
The Revoke operation updates the state of a managed object, effectively
deactivating but not destroying it. The client provides a specific
:term:`revocation_reason_code` indicating why revocation is occurring.
If revocation is due to a key or CA compromise, the managed object is moved
to the compromised state if it is in the pre-active, active, or deactivated
states. If the object has already been destroyed, it will be moved to the
destroyed compromised state. Otherwise, if revocation is due to any other
reason, the managed object is moved to the deactivated state if it is in
the active state.
Errors may be generated during the revocation of a managed object. These
may occur in the following cases:
* the managed object is not revokable (e.g., opaque data object)
* the managed object is not active when revoked for a non-compromise
Destroy
~~~~~~~
The Destroy operation deletes a managed object from the server. Once destroyed,
the object can no longer be retrieved or used for cryptographic operations.
An object can only be destroyed if it is in the pre-active or deactivated
states.
Errors may be generated during the destruction of a managed object. These
may occur in the following cases:
* the managed object is not destroyable (e.g., the object does not exist)
* the managed object is in the active state
Query
~~~~~
The Query operation allows the client to determine what KMIP capabilities are
supported by the server. This set of information may include the following
types of information, depending upon which items the client requests:
* :term:`operation`
* :term:`object_type`
* :term:`vendor_identification`
* :term:`server_information`
* :term:`application_namespace`
* :term:`extension_information`
* :term:`attestation_type`
* :term:`rng_parameters`
* :term:`profile_information`
* :term:`validation_information`
* :term:`capability_information`
* :term:`client_registration_method`
The PyKMIP server currently only includes the supported operations and the
server information in Query responses.
DiscoverVersions
~~~~~~~~~~~~~~~~
The DiscoverVersions operation allows the client to determine which versions
of the KMIP specification are supported by the server.
.. _encrypt:
Encrypt
~~~~~~~
The Encrypt operation allows the client to encrypt data with an existing
managed object stored by the server. Both symmetric and asymmetric encryption
are supported:
Symmetric Key Algorithms
************************
* `3DES`_
* `AES`_
* `Blowfish`_
* `Camellia`_
* `CAST5`_
* `IDEA`_
* `RC4`_
Asymmetric Key Algorithms
*************************
* `RSA`_
Errors may be generated during the encryption. These may occur in the
following cases:
* the encryption key is not accessible to the user
* the encryption key is not in the active state and must be activated
* the encryption key does not have the Encrypt bit set in its usage mask
* the requested encryption algorithm is not supported
* the specified encryption key is not compatible with the requested algorithm
* the requested encryption algorithm requires a block cipher mode
* the requested block cipher mode is not supported
Decrypt
~~~~~~~
The Decrypt operations allows the client to decrypt data with an existing
managed object stored by the server. Both symmetric and asymmetric decryption
are supported. See :ref:`encrypt` above for information on supported algorithms
and the types of errors to expect from the server.
.. _sign:
Sign
~~~~
The Sign operation allows the client to sign data with an existing private key
stored by the server. The following hashing algorithms are supported with
`RSA`_ for signing support.
Hashing Algorithms
******************
* `MD5`_
* `SHA1`_
* `SHA224`_
* `SHA256`_
* `SHA384`_
* `SHA512`_
Errors may be generated during the encryption. These may occur in the
following cases:
* the signing key is not accessible to the user
* the signing key is not a private key
* the signing key is not in the active state and must be activated
* the signing key does not have the Sign bit set in its usage mask
* the requested signing algorithm is not supported
* the signing key is not compatible with the requested signing algorithm
* a padding method is required for the algorithm and was not specified
SignatureVerify
~~~~~~~~~~~~~~~
The SignatureVerify operation allows the client to verify a data signature
with an existing public key stored by the server. See :ref:`sign` above for
information on supported algorithms and the types of errors to expect from
the server.
MAC
~~~
The MAC operation allows the client to compute a message authentication code
on data using an existing managed object stored by the server. Both `HMAC`_
and `CMAC`_ algorithms are supported:
HMAC Hashing Algorithms
***********************
* `MD5`_
* `SHA1`_
* `SHA224`_
* `SHA256`_
* `SHA384`_
* `SHA512`_
CMAC Symmetric Algorithms
*************************
* `3DES`_
* `AES`_
* `Blowfish`_
* `Camellia`_
* `CAST5`_
* `IDEA`_
* `RC4`_
Errors may be generated during the authentication code creation process. These
may occur in the following cases:
* the managed object to use is not accessible to the user
* the managed object to use is not in the active state and must be activated
* the managed object does not have the Generate bit set in its usage mask
* the requested algorithm is not supported for HMAC/CMAC generation
.. Miscellaneous
.. -------------
..
.. Object State
.. ~~~~~~~~~~~~
.. TBD
..
.. Object Operation Policy
.. ~~~~~~~~~~~~~~~~~~~~~~~
.. TBD
..
.. Object Ownership
.. ~~~~~~~~~~~~~~~~
.. TBD
..
.. Object Usage
.. ~~~~~~~~~~~~
.. TBD
.. _`ssl`: https://docs.python.org/dev/library/ssl.html#socket-creation
.. _`sqlalchemy`: https://www.sqlalchemy.org/
.. _`SQLite`: http://docs.sqlalchemy.org/en/latest/dialects/sqlite.html
.. _`pyca/cryptography`: https://cryptography.io/en/latest/
.. _`OpenSSL`: https://www.openssl.org/
.. _`3DES`: https://en.wikipedia.org/wiki/Triple_DES
.. _`AES`: https://en.wikipedia.org/wiki/Advanced_Encryption_Standard
.. _`Blowfish`: https://en.wikipedia.org/wiki/Blowfish_%28cipher%29
.. _`Camellia`: https://en.wikipedia.org/wiki/Camellia_%28cipher%29
.. _`CAST5`: https://en.wikipedia.org/wiki/CAST-128
.. _`IDEA`: https://en.wikipedia.org/wiki/International_Data_Encryption_Algorithm
.. _`RC4`: https://en.wikipedia.org/wiki/RC4
.. _`RSA`: https://en.wikipedia.org/wiki/RSA_%28cryptosystem%29
.. _`MD5`: https://en.wikipedia.org/wiki/MD5
.. _`SHA1`: https://en.wikipedia.org/wiki/SHA-1
.. _`SHA224`: https://en.wikipedia.org/wiki/SHA-2
.. _`SHA256`: https://en.wikipedia.org/wiki/SHA-2
.. _`SHA384`: https://en.wikipedia.org/wiki/SHA-2
.. _`SHA512`: https://en.wikipedia.org/wiki/SHA-2
.. _`HMAC`: https://en.wikipedia.org/wiki/Hash-based_message_authentication_code
.. _`CMAC`: https://en.wikipedia.org/wiki/One-key_MAC

19
tox.ini
View File

@ -1,5 +1,5 @@
[tox]
envlist = pep8,py27,py33,py34,py35,py36,bandit
envlist = pep8,py27,py33,py34,py35,py36,bandit,docs
[testenv]
passenv = TRAVIS TRAVIS_JOB_ID TRAVIS_BRANCH
@ -27,10 +27,21 @@ deps = {[testenv]deps}
commands = bandit -r kmip -n5 -x kmip/tests
[testenv:docs]
deps = sphinx
changedir = docs
deps =
sphinx
sphinx_rtd_theme
basepython = python2.7
commands =
sphinx-apidoc -o {toxinidir}/docs {toxinidir}/kmip/
sphinx-build -b html {toxinidir}/docs {toxinidir}/docs/_build
sphinx-build -j4 -T -W -b html -d {envtmpdir}/doctrees source {envtmpdir}/html
[testenv:docs-linkcheck]
changedir = docs
extras =
deps = {[testenv:docs]deps}
basepython = python2.7
commands =
sphinx-build -W -b linkcheck source {envtmpdir}/html
[flake8]
exclude = .git,.tox,dist,rpmbuild,*.egg-info