From 0dcfe8918ce70e8133a49910e0ccd823c41c27c3 Mon Sep 17 00:00:00 2001 From: Peter Hamilton Date: Mon, 23 Oct 2017 14:32:32 -0400 Subject: [PATCH] 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. --- CHANGES.txt => CHANGELOG.rst | 67 +- docs/Makefile | 20 + docs/conf.py | 359 -------- docs/index.rst | 22 - docs/make.bat | 259 +----- docs/source/changelog.rst | 1 + docs/source/client.rst | 974 ++++++++++++++++++++ docs/source/community.rst | 11 + docs/source/conf.py | 174 ++++ docs/source/development.rst | 123 +++ docs/source/faq.rst | 334 +++++++ docs/source/glossary.rst | 1651 ++++++++++++++++++++++++++++++++++ docs/source/index.rst | 51 ++ docs/source/installation.rst | 38 + docs/source/server.rst | 742 +++++++++++++++ tox.ini | 19 +- 16 files changed, 4208 insertions(+), 637 deletions(-) rename CHANGES.txt => CHANGELOG.rst (89%) create mode 100644 docs/Makefile delete mode 100644 docs/conf.py delete mode 100644 docs/index.rst create mode 100644 docs/source/changelog.rst create mode 100644 docs/source/client.rst create mode 100644 docs/source/community.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/development.rst create mode 100644 docs/source/faq.rst create mode 100644 docs/source/glossary.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/installation.rst create mode 100644 docs/source/server.rst diff --git a/CHANGES.txt b/CHANGELOG.rst similarity index 89% rename from CHANGES.txt rename to CHANGELOG.rst index f93af10..4c0528a 100644 --- a/CHANGES.txt +++ b/CHANGELOG.rst @@ -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 \ No newline at end of file +* Add unit test suite + +.. _`master`: https://github.com/openkmip/pykmip/ \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..c718eb5 --- /dev/null +++ b/docs/Makefile @@ -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) \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 1ec5a2c..0000000 --- a/docs/conf.py +++ /dev/null @@ -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 -# " v 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 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 diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index e715b7c..0000000 --- a/docs/index.rst +++ /dev/null @@ -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` - diff --git a/docs/make.bat b/docs/make.bat index 7683963..0b0e3bf 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -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 ^` where ^ 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 diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst new file mode 100644 index 0000000..09929fe --- /dev/null +++ b/docs/source/changelog.rst @@ -0,0 +1 @@ +.. include:: ../../CHANGELOG.rst diff --git a/docs/source/client.rst b/docs/source/client.rst new file mode 100644 index 0000000..a0013d7 --- /dev/null +++ b/docs/source/client.rst @@ -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 + ... } + ... ) + ... + + + .. py:method:: mac(data, uid=None, algorithm=None) + + Documentation coming soon. diff --git a/docs/source/community.rst b/docs/source/community.rst new file mode 100644 index 0000000..2c261c3 --- /dev/null +++ b/docs/source/community.rst @@ -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 diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..37e9038 --- /dev/null +++ b/docs/source/conf.py @@ -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'), +] + + + diff --git a/docs/source/development.rst b/docs/source/development.rst new file mode 100644 index 0000000..f9738ad --- /dev/null +++ b/docs/source/development.rst @@ -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: ``. 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 diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 0000000..178176c --- /dev/null +++ b/docs/source/faq.rst @@ -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 \ No newline at end of file diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst new file mode 100644 index 0000000..1d0ec43 --- /dev/null +++ b/docs/source/glossary.rst @@ -0,0 +1,1651 @@ +Glossary +======== +.. glossary:: + :sorted: + + alternative_name_type + (enum) (1.2) An enumeration specifying the type associated with an + alternate name value. Used often as part of the alternative name + attribute. + + >>> from kmip import enums + >>> enums.AlternativeNameType.URI + + + ========================= ========== ============ + Name Value KMIP Version + ========================= ========== ============ + UNINTERPRETED_TEXT_STRING 0x00000001 1.2 + URI 0x00000002 1.2 + OBJECT_SERIAL_NUMBER 0x00000003 1.2 + EMAIL_ADDRESS 0x00000004 1.2 + DNS_NAME 0x00000005 1.2 + X500_DISTINGUISHED_NAME 0x00000006 1.2 + IP_ADDRESS 0x00000007 1.2 + ========================= ========== ============ + + application_namespace + (str) (1.0) A string identifying a specific application namespace + supported by the key management server. Often returned as part of + the Query operation. + + attestation_type + (enum) (1.2) An enumeration specifying the type of attestation + measurement included in an attestation credential. Used during client + identification credential processing. + + >>> from kmip import enums + >>> enums.AttestationType.TPM_QUOTE + + + ==================== ========== ============ + Name Value KMIP Version + ==================== ========== ============ + TPM_QUOTE 0x00000001 1.2 + TCG_INTEGRITY_REPORT 0x00000002 1.2 + SAML_ASSERTION 0x00000003 1.2 + ==================== ========== ============ + + batch_error_continuation_option + (enum) (1.0) An enumeration used to control operation batch handling. + + >>> from kmip import enums + >>> enums.BatchErrorContinuationOption.STOP + + + ======== ========== ============ + Name Value KMIP Version + ======== ========== ============ + CONTINUE 0x00000001 1.0 + STOP 0x00000002 1.0 + UNDO 0x00000003 1.0 + ======== ========== ============ + + block_cipher_mode + (enum) (1.0) An enumeration specifying the block cipher mode to use + with a cryptographic algorithm. Used often with sets of cryptographic + parameters. + + >>> from kmip import enums + >>> enums.BlockCipherMode.CTR + + + ==================== ========== ============ + Name Value KMIP Version + ==================== ========== ============ + CBC 0x00000001 1.0 + ECB 0x00000002 1.0 + PCBC 0x00000003 1.0 + CFB 0x00000004 1.0 + OFB 0x00000005 1.0 + CTR 0x00000006 1.0 + CMAC 0x00000007 1.0 + CCM 0x00000008 1.0 + GCM 0x00000009 1.0 + CBC_MAC 0x0000000A 1.0 + XTS 0x0000000B 1.0 + AES_KEY_WRAP_PADDING 0x0000000C 1.0 + NIST_KEY_WRAP 0x0000000D 1.0 + X9_102_AESKW 0x0000000E 1.0 + X9_102_TDKW 0x0000000F 1.0 + X9_102_AKW1 0x00000010 1.0 + X9_102_AKW2 0x00000011 1.0 + AEAD 0x00000012 1.4 + ==================== ========== ============ + + cancellation_result + (enum) (1.0) An enumeration specifying the result of a cancelled + operation. + + >>> from kmip import enums + >>> enums.CancellationResult.FAILED + + + ================ ========== ============ + Name Value KMIP Version + ================ ========== ============ + CANCELED 0x00000001 1.0 + UNABLE_TO_CANCEL 0x00000002 1.0 + COMPLETED 0x00000003 1.0 + FAILED 0x00000004 1.0 + UNAVAILABLE 0x00000005 1.0 + ================ ========== ============ + + capability_information + (dict) (1.3) A dictionary containing information about a set of + KMIP server capabilities. Often obtained from the Query operation + response. + + >>> from kmip import enums + >>> capability_information = { + ... 'streaming_capability': False, + ... 'asynchronous_capability': False, + ... 'attestation_capability': False, + ... 'unwrap_mode': enums.UnwrapMode.PROCESSED, + ... 'destroy_action': enums.DestroyAction.DELETED, + ... 'shredding_algorithm': enums.ShreddingAlgorithm.UNSUPPORTED, + ... 'rng_mode': enums.RNGMode.SHARED_INSTANTIATION, + ... 'batch_undo_capability': False, + ... 'batch_continue_capability': False + ... } + + ================================= ======= ============ + Key Value KMIP Version + ================================= ======= ============ + streaming_capability bool 1.3 + asynchronous_capability bool 1.3 + attestation_capability bool 1.3 + :term:`unwrap_mode` enum 1.3 + :term:`destroy_action` enum 1.3 + :term:`shredding_algorithm` enum 1.3 + :term:`rng_mode` enum 1.3 + batch_undo_capability bool 1.4 + batch_continue_capability bool 1.4 + ================================= ======= ============ + + certificate_request_type + (enum) (1.0) An enumeration specifying the type of the certificate + request sent with a certify operation request. + + >>> from kmip import enums + >>> enums.CertificateRequestType.PEM + + + ====== ========== ============ + Name Value KMIP Version + ====== ========== ============ + CRMF 0x00000001 1.0 + PKCS10 0x00000002 1.0 + PEM 0x00000003 1.0 + PGP 0x00000004 1.0 + ====== ========== ============ + + certificate_type + (enum) (1.0) An enumeration specifying the type of a certificate + object. + + >>> from kmip import enums + >>> enums.CertificateTypeEnum.X_509 + + + ===== ========== ============ + Name Value KMIP Version + ===== ========== ============ + X_509 0x00000001 1.0 + PGP 0x00000002 1.0 + ===== ========== ============ + + client_registration_method + (enum) (1.3) An enumeration specifying a type of registration method + utilized by the client or server. Used often as part of the response + to a Query request. + + >>> from kmip import enums + >>> enums.ClientRegistrationMethod.CLIENT_REGISTERED + + + =================== ========== ============ + Name Value KMIP Version + =================== ========== ============ + UNSPECIFIED 0x00000001 1.3 + SERVER_PREGENERATED 0x00000002 1.3 + SERVER_ON_DEMAND 0x00000003 1.3 + CLIENT_GENERATED 0x00000004 1.3 + CLIENT_REGISTERED 0x00000005 1.3 + =================== ========== ============ + + credential_type + (enum) (1.0) An enumeration specifying the type of a credential object. + Used often as part of a credential structure. + + >>> from kmip import enums + >>> enums.CredentialType.USERNAME_AND_PASSWORD + + + ===================== ========== ============ + Name Value KMIP Version + ===================== ========== ============ + USERNAME_AND_PASSWORD 0x00000001 1.0 + DEVICE 0x00000002 1.1 + ATTESTATION 0x00000003 1.2 + ===================== ========== ============ + + cryptographic_algorithm + (enum) (1.0) An enumeration specifying the cryptographic algorithm to + use for a cryptographic operation. Used often with sets of + cryptographic parameters. + + >>> from kmip import enums + >>> enums.CryptographicAlgorithm.RSA + + + ================= ========== ============ + Name Value KMIP Version + ================= ========== ============ + DES 0x00000001 1.0 + TRIPLE_DES 0x00000002 1.0 + AES 0x00000003 1.0 + RSA 0x00000004 1.0 + DSA 0x00000005 1.0 + ECDSA 0x00000006 1.0 + HMAC_SHA1 0x00000007 1.0 + HMAC_SHA224 0x00000008 1.0 + HMAC_SHA256 0x00000009 1.0 + HMAC_SHA384 0x0000000A 1.0 + HMAC_SHA512 0x0000000B 1.0 + HMAC_MD5 0x0000000C 1.0 + DH 0x0000000D 1.0 + ECDH 0x0000000E 1.0 + ECMQV 0x0000000F 1.0 + BLOWFISH 0x00000010 1.0 + CAMELLIA 0x00000011 1.0 + CAST5 0x00000012 1.0 + IDEA 0x00000013 1.0 + MARS 0x00000014 1.0 + RC2 0x00000015 1.0 + RC4 0x00000016 1.0 + RC5 0x00000017 1.0 + SKIPJACK 0x00000018 1.0 + TWOFISH 0x00000019 1.0 + EC 0x0000001A 1.2 + ONE_TIME_PAD 0x0000001B 1.3 + CHACHA20 0x0000001C 1.4 + POLY1305 0x0000001D 1.4 + CHACHA20_POLY1305 0x0000001E 1.4 + SHA3_224 0x0000001F 1.4 + SHA3_256 0x00000020 1.4 + SHA3_384 0x00000021 1.4 + SHA3_512 0x00000022 1.4 + HMAC_SHA3_224 0x00000023 1.4 + HMAC_SHA3_256 0x00000024 1.4 + HMAC_SHA3_384 0x00000025 1.4 + HMAC_SHA3_512 0x00000026 1.4 + SHAKE_128 0x00000027 1.4 + SHAKE_256 0x00000028 1.4 + ================= ========== ============ + + cryptographic_length + (int) (1.0) A integer specifying the length of a cryptographic object + in bits. Used as a parameter for creating encryption keys of various + types and as an object attribute for cryptographic objects. + + cryptographic_parameters + (dict) (1.0) A dictionary containing key/value pairs representing + settings to be used when performing cryptographic operations. Used as + a parameter to various KMIP operations but can also be set as an + attribute on a KMIP object. + + >>> from kmip import enums + >>> cryptographic_parameters = { + ... 'block_cipher_mode': enums.BlockCipherMode.CTR, + ... 'padding_method': enums.PaddingMethod.PKCS5, + ... 'random_iv': False, + ... 'initial_counter_value': 0 + ... } + + ======================================== ======= ============ + Key Value KMIP Version + ======================================== ======= ============ + :term:`block_cipher_mode` enum 1.0 + :term:`padding_method` enum 1.0 + :term:`hashing_algorithm` enum 1.0 + :term:`key_role_type` enum 1.0 + :term:`digital_signature_algorithm` enum 1.2 + :term:`cryptographic_algorithm` enum 1.2 + random_iv bool 1.2 + iv_length int 1.2 + tag_length int 1.2 + fixed_field_length int 1.2 + invocation_field_length int 1.2 + counter_length int 1.2 + initial_counter_value int 1.2 + salt_length int 1.4 + :term:`mask_generator` enum 1.4 + :term:`mask_generator_hashing_algorithm` enum 1.4 + p_source bytes 1.4 + trailer_field int 1.4 + ======================================== ======= ============ + + cryptographic_usage_mask + (enum) (1.0) An enumeration specifying a cryptographic capability, + usually associated with a managed object. Often used in list form + (e.g., [CryptographicUsageMask.SIGN, CryptographicUsageMask.VERIFY]). + + >>> from kmip import enums + >>> enums.CryptographicUsageMask.ENCRYPT + + + =================== ========== ============ + Name Value KMIP Version + =================== ========== ============ + SIGN 0x00000001 1.0 + VERIFY 0x00000002 1.0 + ENCRYPT 0x00000004 1.0 + DECRYPT 0x00000008 1.0 + WRAP_KEY 0x00000010 1.0 + UNWRAP_KEY 0x00000020 1.0 + EXPORT 0x00000040 1.0 + MAC_GENERATE 0x00000080 1.0 + MAC_VERIFY 0x00000100 1.0 + DERIVE_KEY 0x00000200 1.0 + CONTENT_COMMITMENT 0x00000400 1.0 + KEY_AGREEMENT 0x00000800 1.0 + CERTIFICATE_SIGN 0x00001000 1.0 + CRL_SIGN 0x00002000 1.0 + GENERATE_CRYPTOGRAM 0x00004000 1.0 + VALIDATE_CRYPTOGRAM 0x00008000 1.0 + TRANSLATE_ENCRYPT 0x00010000 1.0 + TRANSLATE_DECRYPT 0x00020000 1.0 + TRANSLATE_WRAP 0x00040000 1.0 + TRANSLATE_UNWRAP 0x00080000 1.0 + =================== ========== ============ + + derivation_parameters + (dict) (1.0) A dictionary containing key/value pairs representing + settings to be used when performing key derivation operations. Used + as a parameter to the DeriveKey operation. + + >>> from kmip import enums + >>> derivation_parameters = { + ... 'cryptographic_parameters': {...}, + ... 'initialization_vector': b'\x01\x02\x03\x04', + ... 'derivation_data': b'\xFF\xFF\xFF\xFF', + ... 'salt': b'\x00\x00\xFF\xFF', + ... 'iteration_count': 1000 + ... } + + ======================== ======= ============ + Key Value KMIP Version + ======================== ======= ============ + cryptographic_parameters dict 1.0 + initialization_vector bytes 1.0 + derivation_data bytes 1.0 + salt bytes 1.0 + iteration_count int 1.0 + ======================== ======= ============ + + drbg_algorithm + (enum) (1.3) An enumeration specifying a deterministic random bit + generator. Used often to describe a random number generator. + + >>> from kmip import enums + >>> enums.DRBGAlgorithm.DUAL_EC + + + =========== ========== ============ + Name Value KMIP Version + =========== ========== ============ + UNSPECIFIED 0x00000001 1.3 + DUAL_EC 0x00000002 1.3 + HASH 0x00000003 1.3 + HMAC 0x00000004 1.3 + CTR 0x00000005 1.3 + =========== ========== ============ + + derivation_method + (enum) (1.0) An enumeration specifying a key derivation method to be + used to derive a new key. Used as a parameter to the DeriveKey + operation. + + >>> from kmip import enums + >>> enums.DerivationMethod.PBKDF2 + + + =============== ========== ============ + Name Value KMIP Version + =============== ========== ============ + PBKDF2 0x00000001 1.0 + HASH 0x00000002 1.0 + HMAC 0x00000003 1.0 + ENCRYPT 0x00000004 1.0 + NIST800_108_C 0x00000005 1.0 + NIST800_108_F 0x00000006 1.0 + NIST800_108_DPI 0x00000007 1.0 + ASYMMETRIC_KEY 0x00000008 1.4 + =============== ========== ============ + + destroy_action + (enum) (1.3) An enumeration specifying methods of data disposal used + by a KMIP server. Used often as part of the response to a Query + request. + + >>> from kmip import enums + >>> enums.DestroyAction.SHREDDED + + + ===================== ========== ============ + Name Value KMIP Version + ===================== ========== ============ + UNSPECIFIED 0x00000001 1.3 + KEY_MATERIAL_DELETED 0x00000002 1.3 + KEY_MATERIAL_SHREDDED 0x00000003 1.3 + METADATA_DELETED 0x00000004 1.3 + METADATA_SHREDDED 0x00000005 1.3 + DELETED 0x00000006 1.3 + SHREDDED 0x00000007 1.3 + ===================== ========== ============ + + digital_signature_algorithm + (enum) (1.1) An enumeration specifying a digital signature algorithm, + usually associated with a signed object. Used often with sets of + cryptographic parameters. + + >>> from kmip import enums + >>> enums.DigitalSignatureAlgorithm.SHA256_WITH_RSA_ENCRYPTION + + + ============================ ========== ============ + Name Value KMIP Version + ============================ ========== ============ + MD2_WITH_RSA_ENCRYPTION 0x00000001 1.1 + MD5_WITH_RSA_ENCRYPTION 0x00000002 1.1 + SHA1_WITH_RSA_ENCRYPTION 0x00000003 1.1 + SHA224_WITH_RSA_ENCRYPTION 0x00000004 1.1 + SHA256_WITH_RSA_ENCRYPTION 0x00000005 1.1 + SHA384_WITH_RSA_ENCRYPTION 0x00000006 1.1 + SHA512_WITH_RSA_ENCRYPTION 0x00000007 1.1 + RSASSA_PSS 0x00000008 1.1 + DSA_WITH_SHA1 0x00000009 1.1 + DSA_WITH_SHA224 0x0000000A 1.1 + DSA_WITH_SHA256 0x0000000B 1.1 + ECDSA_WITH_SHA1 0x0000000C 1.1 + ECDSA_WITH_SHA224 0x0000000D 1.1 + ECDSA_WITH_SHA256 0x0000000E 1.1 + ECDSA_WITH_SHA384 0x0000000F 1.1 + ECDSA_WITH_SHA512 0x00000010 1.1 + SHA3_256_WITH_RSA_ENCRYPTION 0x00000011 1.4 + SHA3_384_WITH_RSA_ENCRYPTION 0x00000012 1.4 + SHA3_512_WITH_RSA_ENCRYPTION 0x00000013 1.4 + ============================ ========== ============ + + encoding_option + (enum) (1.1) An enumeration specifying the encoding of an object + before it is cryptographically wrapped. Used in various key wrapping + metadata structures. + + >>> from kmip import enums + >>> enums.EncodingOption.NO_ENCODING + + + ============= ========== ============ + Name Value KMIP Version + ============= ========== ============ + NO_ENCODING 0x00000001 1.1 + TTLV_ENCODING 0x00000002 1.1 + ============= ========== ============ + + encryption_key_information + (dict) (1.0) A dictionary containing information on the encryption key + used for key wrapping. + + >>> from kmip import enums + >>> encryption_key_information = { + ... 'unique_identifier': '123e4567-e89b-12d3-a456-426655440000', + ... 'cryptographic_parameters': {...} + ... } + + ======================== ======= ============ + Key Value KMIP Version + ======================== ======= ============ + unique_identifier string 1.0 + cryptographic_parameters dict 1.0 + ======================== ======= ============ + + extension_information + (dict) (1.1) A dictionary containing information on a specific KMIP + specification extension supported by a KMIP server. Often returned as + part of a Query operation response. + + >>> from kmip import enums + >>> extension_information = { + ... 'extension_name': 'ACME LOCATION', + ... 'extension_tag': 0x0054aa01, + ... 'extension_type': 0x00000007 + ... } + + ======================== ======= ============ + Key Value KMIP Version + ======================== ======= ============ + extension_name string 1.1 + extension_tag int 1.1 + extension_type int 1.1 + ======================== ======= ============ + + fips186_variation + (enum) (1.3) An enumeration specifying a FIPS 186 variation. Used + often to describe a random number generator. + + >>> from kmip import enums + >>> enums.FIPS186Variation.K_CHANGE_NOTICE + + + ================== ========== ============ + Name Value KMIP Version + ================== ========== ============ + UNSPECIFIED 0x00000001 1.3 + GP_X_ORIGINAL 0x00000002 1.3 + GP_X_CHANGE_NOTICE 0x00000003 1.3 + X_ORIGINAL 0x00000004 1.3 + X_CHANGE_NOTICE 0x00000005 1.3 + K_ORIGINAL 0x00000006 1.3 + K_CHANGE_NOTICE 0x00000007 1.3 + ================== ========== ============ + + hashing_algorithm + (enum) (1.0) An enumeration specifying the hashing method to use with + a cryptographic algorithm. Used often with sets of cryptographic + parameters. + + >>> from kmip import enums + >>> enums.HashingAlgorithm.MD5 + + + =========== ========== ============ + Name Value KMIP Version + =========== ========== ============ + MD2 0x00000001 1.0 + MD4 0x00000002 1.0 + MD5 0x00000003 1.0 + SHA_1 0x00000004 1.0 + SHA_224 0x00000005 1.0 + SHA_256 0x00000006 1.0 + SHA_384 0x00000007 1.0 + SHA_512 0x00000008 1.0 + RIPEMD_160 0x00000009 1.0 + TIGER 0x0000000A 1.0 + WHIRLPOOL 0x0000000B 1.0 + SHA_512_224 0x0000000C 1.2 + SHA_512_256 0x0000000D 1.2 + SHA3_224 0x0000000E 1.4 + SHA3_256 0x0000000F 1.4 + SHA3_384 0x00000010 1.4 + SHA3_512 0x00000011 1.4 + =========== ========== ============ + + initial_date + (int) (1.0) An integer specifying, in seconds since the Epoch, the + date and time when a managed object first entered the pre-active + state. This occurs when the object is first created or registered + with the key management appliance. This value is set by the server + on every managed object and cannot be changed. + + key_compression_type + (enum) (1.0) An enumeration specifying the key compression used for + an elliptic curve public key. Used as a key value attribute and as a + parameter for the Get operation. + + >>> from kmip import enums + >>> enums.KeyCompressionType.EC_PUBLIC_KEY_TYPE_UNCOMPRESSED + + + ========================================= ========== ============ + Name Value KMIP Version + ========================================= ========== ============ + EC_PUBLIC_KEY_TYPE_UNCOMPRESSED 0x00000001 1.0 + EC_PUBLIC_KEY_TYPE_X9_62_COMPRESSED_PRIME 0x00000002 1.0 + EC_PUBLIC_KEY_TYPE_X9_62_COMPRESSED_CHAR2 0x00000003 1.0 + EC_PUBLIC_KEY_TYPE_X9_62_HYBRID 0x00000004 1.0 + ========================================= ========== ============ + + key_format_type + (enum) (1.0) An enumeration specifying the format of key material. + Used in various ways as a key value attribute, as well as a + parameter to the Get operation. + + >>> from kmip import enums + >>> enums.KeyFormatType.RAW + + + ============================= ========== ============ + Name Value KMIP Version + ============================= ========== ============ + RAW 0x00000001 1.0 + OPAQUE 0x00000002 1.0 + PKCS_1 0x00000003 1.0 + PKCS_8 0x00000004 1.0 + X_509 0x00000005 1.0 + EC_PRIVATE_KEY 0x00000006 1.0 + TRANSPARENT_SYMMETRIC_KEY 0x00000007 1.0 + TRANSPARENT_DSA_PRIVATE_KEY 0x00000008 1.0 + TRANSPARENT_DSA_PUBLIC_KEY 0x00000009 1.0 + TRANSPARENT_RSA_PRIVATE_KEY 0x0000000a 1.0 + TRANSPARENT_RSA_PUBLIC_KEY 0x0000000b 1.0 + TRANSPARENT_DH_PRIVATE_KEY 0x0000000c 1.0 + TRANSPARENT_DH_PUBLIC_KEY 0x0000000d 1.0 + TRANSPARENT_ECDSA_PRIVATE_KEY 0x0000000e 1.0 + TRANSPARENT_ECDSA_PUBLIC_KEY 0x0000000f 1.0 + TRANSPARENT_ECDH_PRIVATE_KEY 0x00000010 1.0 + TRANSPARENT_ECDH_PUBLIC_KEY 0x00000011 1.0 + TRANSPARENT_ECMQV_PRIVATE_KEY 0x00000012 1.0 + TRANSPARENT_ECMQV_PUBLIC_KEY 0x00000013 1.0 + TRANSPARENT_EC_PRIVATE_KEY 0x00000014 1.3 + TRANSPARENT_EC_PUBLIC_KEY 0x00000015 1.3 + PKCS_12 0x00000016 1.4 + ============================= ========== ============ + + key_role_type + (enum) (1.0) An enumeration specifying the key role type of the + associated cryptographic key. Used often with sets of cryptographic + parameters. + + >>> from kmip import enums + >>> enums.KeyRoleType.KEK + + + ========= ========== ============ + Name Value KMIP Version + ========= ========== ============ + BDK 0x00000001 1.0 + CVK 0x00000002 1.0 + DEK 0x00000003 1.0 + MKAC 0x00000004 1.0 + MKSMC 0x00000005 1.0 + MKSMI 0x00000006 1.0 + MKDAC 0x00000007 1.0 + MKDN 0x00000008 1.0 + MKCP 0x00000009 1.0 + MKOTH 0x0000000A 1.0 + KEK 0x0000000B 1.0 + MAC_16609 0x0000000C 1.0 + MAC_97971 0x0000000D 1.0 + MAC_97972 0x0000000E 1.0 + MAC_97973 0x0000000F 1.0 + MAC_97974 0x00000010 1.0 + MAC_97975 0x00000011 1.0 + ZPK 0x00000012 1.0 + PVKIBM 0x00000013 1.0 + PVKPVV 0x00000014 1.0 + PVKOTH 0x00000015 1.0 + DUKPT 0x00000016 1.4 + IV 0x00000017 1.4 + TRKBK 0x00000018 1.4 + ========= ========== ============ + + key_value_location_type + (enum) (1.2) An enumeration specifying the type of key value location + identifier. Used in cases where a key value is stored outside a key + server. + + >>> from kmip import enums + >>> enums.KeyValueLocationType.URI + + + ========================= ========== ============ + Name Value KMIP Version + ========================= ========== ============ + UNINTERPRETED_TEXT_STRING 0x00000001 1.2 + URI 0x00000002 1.2 + ========================= ========== ============ + + key_wrap_type + (enum) (1.4) An enumeration specifying the type of key wrap used to + access a managed object. Used to specify key wrapping in Get and + Export operations. + + >>> from kmip import enums + >>> enums.KeyWrapType.NOT_WRAPPED + + + ============= ========== ============ + Name Value KMIP Version + ============= ========== ============ + NOT_WRAPPED 0x00000001 1.4 + AS_REGISTERED 0x00000002 1.4 + ============= ========== ============ + + key_wrapping_data + (dict) (1.0) A dictionary containing information on a cryptographic + key wrapping mechanism used to wrap a key value. + + >>> from kmip import enums + >>> key_wrapping_data = { + ... 'wrapping_method': enums.WrappingMethod.ENCRYPT, + ... 'encryption_key_information': {...}, + ... 'iv_counter_nonce': b'\x01\x02\x03\x04', + ... 'encoding_option': enums.EncodingOption.NO_ENCODING + ... } + + ============================= ======= ============ + Key Value KMIP Version + ============================= ======= ============ + :term:`wrapping_method` enum 1.0 + encryption_key_information dict 1.0 + mac_signature_key_information dict 1.0 + mac_signature bytes 1.0 + iv_counter_nonce bytes 1.0 + :term:`encoding_option` enum 1.1 + ============================= ======= ============ + + key_wrapping_specification + (dict) (1.0) A dictionary containing settings defining how an object + should be cryptographically wrapped. Used as a parameter for the Get + operation to retrieve cryptographically wrapped objects. + + >>> from kmip import enums + >>> key_wrapping_specification = { + ... 'wrapping_method': enums.WrappingMethod.ENCRYPT, + ... 'encryption_key_information': {...}, + ... 'attribute_names': [ + ... 'Cryptographic Algorithm', + ... 'Cryptographic Length' + ... ] + ... } + + ============================= ======= ============ + Key Value KMIP Version + ============================= ======= ============ + :term:`wrapping_method` enum 1.0 + encryption_key_information dict 1.0 + mac_signature_key_information dict 1.0 + attribute_names list 1.0 + :term:`encoding_option` enum 1.1 + ============================= ======= ============ + + link_type + (enum) (1.0) An enumeration specifying the type of link connecting two + managed objects. Used often as an object attribute. + + >>> from kmip import enums + >>> enums.LinkType.PUBLIC_KEY_LINK + + + =========================== ========== ============ + Name Value KMIP Version + =========================== ========== ============ + CERTIFICATE_LINK 0x00000101 1.0 + PUBLIC_KEY_LINK 0x00000102 1.0 + PRIVATE_KEY_LINK 0x00000103 1.0 + DERIVATION_BASE_OBJECT_LINK 0x00000104 1.0 + DERIVED_KEY_LINK 0x00000105 1.0 + REPLACEMENT_OBJECT_LINK 0x00000106 1.0 + REPLACED_OBJECT_LINK 0x00000107 1.0 + PARENT_LINK 0x00000108 1.2 + CHILD_LINK 0x00000109 1.2 + PREVIOUS_LINK 0x0000010a 1.2 + NEXT_LINK 0x0000010b 1.2 + PKCS12_CERTIFICATE_LINK 0x0000010c 1.4 + PKCS12_PASSWORD_LINK 0x0000010d 1.4 + =========================== ========== ============ + + mac_signature_key_information + (dict) (1.0) A dictionary containing information on the MAC/signature + key used for key wrapping. + + >>> from kmip import enums + >>> mac_signature_key_information = { + ... 'unique_identifier': '123e4567-e89b-12d3-a456-426655440000', + ... 'cryptographic_parameters': {...} + ... } + + ======================== ======= ============ + Key Value KMIP Version + ======================== ======= ============ + unique_identifier string 1.0 + cryptographic_parameters dict 1.0 + ======================== ======= ============ + + mask_generator_hashing_algorithm + (enum) (1.4) Another name for a hash algorithm. See hashing_algorithm. + + mask_generator + (enum) (1.4) An enumeration specifying the mask generation function to + use for a cryptographic operation. Used often with sets of + cryptographic parameters. + + >>> from kmip import enums + >>> enums.MaskGenerator.MGF1 + + + ==== ========== ============ + Name Value KMIP Version + ==== ========== ============ + MGF1 0x00000001 1.4 + ==== ========== ============ + + name + (str) (1.0) A string specifying the name of a managed object stored by + the server. It can be used in addition to the :term:`unique_identifier` + to identify an object and can be used as a filter with the Locate + operation. + + name_type + (enum) (1.0) An enumeration specifying the type of name value used in + a name attribute structure. + + >>> from kmip import enums + >>> enums.NameType.URI + + + ========================= ========== ============ + Name Value KMIP Version + ========================= ========== ============ + UNINTERPRETED_TEXT_STRING 0x00000001 1.0 + URI 0x00000002 1.0 + ========================= ========== ============ + + object_group_member + (enum) (1.1) An enumeration specifying whether or not a group object + has been returned to a client before the current request. Used as a + filtering flag for the Locate operation. + + >>> from kmip import enums + >>> enums.ObjectGroupMember.GROUP_MEMBER_FRESH + + + ==================== ========== ============ + Name Value KMIP Version + ==================== ========== ============ + GROUP_MEMBER_FRESH 0x00000001 1.1 + GROUP_MEMBER_DEFAULT 0x00000002 1.1 + ==================== ========== ============ + + object_type + (enum) (1.0) An enumeration specifying the type of a managed object. + Used as an attribute for every managed object on a key server. + + >>> from kmip import enums + >>> enums.ObjectType.SYMMETRIC_KEY + + + ============= ========== ============ + Name Value KMIP Version + ============= ========== ============ + CERTIFICATE 0x00000001 1.0 + SYMMETRIC_KEY 0x00000002 1.0 + PUBLIC_KEY 0x00000003 1.0 + PRIVATE_KEY 0x00000004 1.0 + SPLIT_KEY 0x00000005 1.0 + TEMPLATE 0x00000006 1.0 + SECRET_DATA 0x00000007 1.0 + OPAQUE_DATA 0x00000008 1.0 + PGP_KEY 0x00000009 1.2 + ============= ========== ============ + + opaque_data_type + (enum) (1.0) An enumeration specifying the type of the associated + opaque data object. Note that no values have ever been specified by + the KMIP specification. A custom NONE value is included in PyKMIP + as a default. This value will only be recognized by the PyKMIP + server. + + >>> from kmip import enums + >>> enums.OpaqueDataType.NONE + + + ==== ========== ============ + Name Value KMIP Version + ==== ========== ============ + NONE 0x80000000 -- + ==== ========== ============ + + operation + (enum) (1.0) An enumeration specifying a KMIP operation. Used in KMIP + requests. + + >>> from kmip import enums + >>> enums.Operation.GET + + + ==================== ========== ============ + Name Value KMIP Version + ==================== ========== ============ + CREATE 0x00000001 1.0 + CREATE_KEY_PAIR 0x00000002 1.0 + REGISTER 0x00000003 1.0 + REKEY 0x00000004 1.0 + DERIVE_KEY 0x00000005 1.0 + CERTIFY 0x00000006 1.0 + RECERTIFY 0x00000007 1.0 + LOCATE 0x00000008 1.0 + CHECK 0x00000009 1.0 + GET 0x0000000a 1.0 + GET_ATTRIBUTES 0x0000000b 1.0 + GET_ATTRIBUTE_LIST 0x0000000c 1.0 + ADD_ATTRIBUTE 0x0000000d 1.0 + MODIFY_ATTRIBUTE 0x0000000e 1.0 + DELETE_ATTRIBUTE 0x0000000f 1.0 + OBTAIN_LEASE 0x00000010 1.0 + GET_USAGE_ALLOCATION 0x00000011 1.0 + ACTIVATE 0x00000012 1.0 + REVOKE 0x00000013 1.0 + DESTROY 0x00000014 1.0 + ARCHIVE 0x00000015 1.0 + RECOVER 0x00000016 1.0 + VALIDATE 0x00000017 1.0 + QUERY 0x00000018 1.0 + CANCEL 0x00000019 1.0 + POLL 0x0000001a 1.0 + NOTIFY 0x0000001b 1.0 + PUT 0x0000001c 1.0 + REKEY_KEY_PAIR 0x0000001d 1.1 + DISCOVER_VERSIONS 0x0000001e 1.1 + ENCRYPT 0x0000001f 1.2 + DECRYPT 0x00000020 1.2 + SIGN 0x00000021 1.2 + SIGNATURE_VERIFY 0x00000022 1.2 + MAC 0x00000023 1.2 + MAC_VERIFY 0x00000024 1.2 + RNG_RETRIEVE 0x00000025 1.2 + RNG_SEED 0x00000026 1.2 + HASH 0x00000027 1.2 + CREATE_SPLIT_KEY 0x00000028 1.2 + JOIN_SPLIT_KEY 0x00000029 1.2 + IMPORT 0x0000002a 1.4 + EXPORT 0x0000002b 1.4 + ==================== ========== ============ + + operation_policy_name + (str) (1.0) A string specifying the name of the operation policy that + should be used for access control decisions for a managed object. One + operation policy name attribute can be set per managed object by the + server. Once set it cannot be changed by the client. + + padding_method + (enum) (1.0) An enumeration specifying the padding method to use to + pad data during cryptographic operations. Used often with sets of + cryptographic parameters. + + >>> from kmip import enums + >>> enums.PaddingMethod.PKCS5 + + + ========= ========== ============ + Name Value KMIP Version + ========= ========== ============ + NONE 0x00000001 1.0 + OAEP 0x00000002 1.0 + PKCS5 0x00000003 1.0 + SSL3 0x00000004 1.0 + ZEROS 0x00000005 1.0 + ANSI_X923 0x00000006 1.0 + ISO_10126 0x00000007 1.0 + PKCS1v15 0x00000008 1.0 + X931 0x00000009 1.0 + PSS 0x0000000A 1.0 + ========= ========== ============ + + profile_name + (enum) (1.3) An enumeration specifying a profile supported by the + client or server. Used often as part of the response to a Query + request. + + >>> from kmip import enums + >>> enums.ProfileName.BASELINE_SERVER_BASIC_KMIPv12 + + + ======================================================= ========== ============ + Name Value KMIP Version + ======================================================= ========== ============ + BASELINE_SERVER_BASIC_KMIPv12 0x00000001 1.3 + BASELINE_SERVER_TLSv12_KMIPv12 0x00000002 1.3 + BASELINE_CLIENT_BASIC_KMIPv12 0x00000003 1.3 + BASELINE_CLIENT_TLSv12_KMIPv12 0x00000004 1.3 + COMPLETE_SERVER_BASIC_KMIPv12 0x00000005 1.3 + COMPLETE_SERVER_TLSv12_KMIPv12 0x00000006 1.3 + TAPE_LIBRARY_CLIENT_KMIPv10 0x00000007 1.3 + TAPE_LIBRARY_CLIENT_KMIPv11 0x00000008 1.3 + TAPE_LIBRARY_CLIENT_KMIPv12 0x00000009 1.3 + TAPE_LIBRARY_SERVER_KMIPv10 0x0000000a 1.3 + TAPE_LIBRARY_SERVER_KMIPv11 0x0000000b 1.3 + TAPE_LIBRARY_SERVER_KMIPv12 0x0000000c 1.3 + SYMMETRIC_KEY_LIFECYCLE_CLIENT_KMIPv10 0x0000000d 1.3 + SYMMETRIC_KEY_LIFECYCLE_CLIENT_KMIPv11 0x0000000e 1.3 + SYMMETRIC_KEY_LIFECYCLE_CLIENT_KMIPv12 0x0000000f 1.3 + SYMMETRIC_KEY_LIFECYCLE_SERVER_KMIPv10 0x00000010 1.3 + SYMMETRIC_KEY_LIFECYCLE_SERVER_KMIPv11 0x00000011 1.3 + SYMMETRIC_KEY_LIFECYCLE_SERVER_KMIPv12 0x00000012 1.3 + ASYMMETRIC_KEY_LIFECYCLE_CLIENT_KMIPv10 0x00000013 1.3 + ASYMMETRIC_KEY_LIFECYCLE_CLIENT_KMIPv11 0x00000014 1.3 + ASYMMETRIC_KEY_LIFECYCLE_CLIENT_KMIPv12 0x00000015 1.3 + ASYMMETRIC_KEY_LIFECYCLE_SERVER_KMIPv10 0x00000016 1.3 + ASYMMETRIC_KEY_LIFECYCLE_SERVER_KMIPv11 0x00000017 1.3 + ASYMMETRIC_KEY_LIFECYCLE_SERVER_KMIPv12 0x00000018 1.3 + BASIC_CRYPTOGRAPHIC_CLIENT_KMIPv12 0x00000019 1.3 + BASIC_CRYPTOGRAPHIC_SERVER_KMIPv12 0x0000001a 1.3 + ADVANCED_CRYPTOGRAPHIC_CLIENT_KMIPv12 0x0000001b 1.3 + ADVANCED_CRYPTOGRAPHIC_SERVER_KMIPv12 0x0000001c 1.3 + RNG_CRYPTOGRAPHIC_CLIENT_KMIPv12 0x0000001d 1.3 + RNG_CRYPTOGRAPHIC_SERVER_KMIPv12 0x0000001e 1.3 + BASIC_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv10 0x0000001f 1.3 + INTERMEDIATE_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv10 0x00000020 1.3 + ADVANCED_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv10 0x00000021 1.3 + BASIC_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv11 0x00000022 1.3 + INTERMEDIATE_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv11 0x00000023 1.3 + ADVANCED_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv11 0x00000024 1.3 + BASIC_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv12 0x00000025 1.3 + INTERMEDIATE_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv12 0x00000026 1.3 + ADVANCED_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv12 0x00000027 1.3 + SYMMETRIC_KEY_FOUNDRY_SERVER_KMIPv10 0x00000028 1.3 + SYMMETRIC_KEY_FOUNDRY_SERVER_KMIPv11 0x00000029 1.3 + SYMMETRIC_KEY_FOUNDRY_SERVER_KMIPv12 0x0000002a 1.3 + OPAQUE_MANAGED_OBJECT_STORE_CLIENT_KMIPv10 0x0000002b 1.3 + OPAQUE_MANAGED_OBJECT_STORE_CLIENT_KMIPv11 0x0000002c 1.3 + OPAQUE_MANAGED_OBJECT_STORE_CLIENT_KMIPv12 0x0000002d 1.3 + OPAQUE_MANAGED_OBJECT_STORE_SERVER_KMIPv10 0x0000002e 1.3 + OPAQUE_MANAGED_OBJECT_STORE_SERVER_KMIPv11 0x0000002f 1.3 + OPAQUE_MANAGED_OBJECT_STORE_SERVER_KMIPv12 0x00000030 1.3 + SUITE_B_MINLOS_128_CLIENT_KMIPv10 0x00000031 1.3 + SUITE_B_MINLOS_128_CLIENT_KMIPv11 0x00000032 1.3 + SUITE_B_MINLOS_128_CLIENT_KMIPv12 0x00000033 1.3 + SUITE_B_MINLOS_128_SERVER_KMIPv10 0x00000034 1.3 + SUITE_B_MINLOS_128_SERVER_KMIPv11 0x00000035 1.3 + SUITE_B_MINLOS_128_SERVER_KMIPv12 0x00000036 1.3 + SUITE_B_MINLOS_192_CLIENT_KMIPv10 0x00000037 1.3 + SUITE_B_MINLOS_192_CLIENT_KMIPv11 0x00000038 1.3 + SUITE_B_MINLOS_192_CLIENT_KMIPv12 0x00000039 1.3 + SUITE_B_MINLOS_192_SERVER_KMIPv10 0x0000003a 1.3 + SUITE_B_MINLOS_192_SERVER_KMIPv11 0x0000003b 1.3 + SUITE_B_MINLOS_192_SERVER_KMIPv12 0x0000003c 1.3 + STORAGE_ARRAY_WITH_SELF_ENCRYPTING_DRIVE_CLIENT_KMIPv10 0x0000003d 1.3 + STORAGE_ARRAY_WITH_SELF_ENCRYPTING_DRIVE_CLIENT_KMIPv11 0x0000003e 1.3 + STORAGE_ARRAY_WITH_SELF_ENCRYPTING_DRIVE_CLIENT_KMIPv12 0x0000003f 1.3 + STORAGE_ARRAY_WITH_SELF_ENCRYPTING_DRIVE_SERVER_KMIPv10 0x00000040 1.3 + STORAGE_ARRAY_WITH_SELF_ENCRYPTING_DRIVE_SERVER_KMIPv11 0x00000041 1.3 + STORAGE_ARRAY_WITH_SELF_ENCRYPTING_DRIVE_SERVER_KMIPv12 0x00000042 1.3 + HTTPS_CLIENT_KMIPv10 0x00000043 1.3 + HTTPS_CLIENT_KMIPv11 0x00000044 1.3 + HTTPS_CLIENT_KMIPv12 0x00000045 1.3 + HTTPS_SERVER_KMIPv10 0x00000046 1.3 + HTTPS_SERVER_KMIPv11 0x00000047 1.3 + HTTPS_SERVER_KMIPv12 0x00000048 1.3 + JSON_CLIENT_KMIPv10 0x00000049 1.3 + JSON_CLIENT_KMIPv11 0x0000004a 1.3 + JSON_CLIENT_KMIPv12 0x0000004b 1.3 + JSON_SERVER_KMIPv10 0x0000004c 1.3 + JSON_SERVER_KMIPv11 0x0000004d 1.3 + JSON_SERVER_KMIPv12 0x0000004e 1.3 + XML_CLIENT_KMIPv10 0x0000004f 1.3 + XML_CLIENT_KMIPv11 0x00000050 1.3 + XML_CLIENT_KMIPv12 0x00000051 1.3 + XML_SERVER_KMIPv10 0x00000052 1.3 + XML_SERVER_KMIPv11 0x00000053 1.3 + XML_SERVER_KMIPv12 0x00000054 1.3 + BASELINE_SERVER_BASIC_KMIPv13 0x00000055 1.3 + BASELINE_SERVER_TLSv12_KMIPv13 0x00000056 1.3 + BASELINE_CLIENT_BASIC_KMIPv13 0x00000057 1.3 + BASELINE_CLIENT_TLSv12_KMIPv13 0x00000058 1.3 + COMPLETE_SERVER_BASIC_KMIPv13 0x00000059 1.3 + COMPLETE_SERVER_TLSv12_KMIPv13 0x0000005a 1.3 + TAPE_LIBRARY_CLIENT_KMIPv13 0x0000005b 1.3 + TAPE_LIBRARY_SERVER_KMIPv13 0x0000005c 1.3 + SYMMETRIC_KEY_LIFECYCLE_CLIENT_KMIPv13 0x0000005d 1.3 + SYMMETRIC_KEY_LIFECYCLE_SERVER_KMIPv13 0x0000005e 1.3 + ASYMMETRIC_KEY_LIFECYCLE_CLIENT_KMIPv13 0x0000005f 1.3 + ASYMMETRIC_KEY_LIFECYCLE_SERVER_KMIPv13 0x00000060 1.3 + BASIC_CRYPTOGRAPHIC_CLIENT_KMIPv13 0x00000061 1.3 + BASIC_CRYPTOGRAPHIC_SERVER_KMIPv13 0x00000062 1.3 + ADVANCED_CRYPTOGRAPHIC_CLIENT_KMIPv13 0x00000063 1.3 + ADVANCED_CRYPTOGRAPHIC_SERVER_KMIPv13 0x00000064 1.3 + RNG_CRYPTOGRAPHIC_CLIENT_KMIPv13 0x00000065 1.3 + RNG_CRYPTOGRAPHIC_SERVER_KMIPv13 0x00000066 1.3 + BASIC_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv13 0x00000067 1.3 + INTERMEDIATE_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv13 0x00000068 1.3 + ADVANCED_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv13 0x00000069 1.3 + SYMMETRIC_KEY_FOUNDRY_SERVER_KMIPv13 0x0000006a 1.3 + OPAQUE_MANAGED_OBJECT_STORE_CLIENT_KMIPv13 0x0000006b 1.3 + OPAQUE_MANAGED_OBJECT_STORE_SERVER_KMIPv13 0x0000006c 1.3 + SUITE_B_MINLOS_128_CLIENT_KMIPv13 0x0000006d 1.3 + SUITE_B_MINLOS_128_SERVER_KMIPv13 0x0000006e 1.3 + SUITE_B_MINLOS_192_CLIENT_KMIPv13 0x0000006f 1.3 + SUITE_B_MINLOS_192_SERVER_KMIPv13 0x00000070 1.3 + STORAGE_ARRAY_WITH_SELF_ENCRYPTING_DRIVE_CLIENT_KMIPv13 0x00000071 1.3 + STORAGE_ARRAY_WITH_SELF_ENCRYPTING_DRIVE_SERVER_KMIPv13 0x00000072 1.3 + HTTPS_CLIENT_KMIPv13 0x00000073 1.3 + HTTPS_SERVER_KMIPv13 0x00000074 1.3 + JSON_CLIENT_KMIPv13 0x00000075 1.3 + JSON_SERVER_KMIPv13 0x00000076 1.3 + XML_CLIENT_KMIPv13 0x00000077 1.3 + XML_SERVER_KMIPv13 0x00000078 1.3 + BASELINE_SERVER_BASIC_KMIPv14 0x00000079 1.4 + BASELINE_SERVER_TLSv12_KMIPv14 0x0000007a 1.4 + BASELINE_CLIENT_BASIC_KMIPv14 0x0000007b 1.4 + BASELINE_CLIENT_TLSv12_KMIPv14 0x0000007c 1.4 + COMPLETE_SERVER_BASIC_KMIPv14 0x0000007d 1.4 + COMPLETE_SERVER_TLSv12_KMIPv14 0x0000007e 1.4 + TAPE_LIBRARY_CLIENT_KMIPv14 0x0000007f 1.4 + TAPE_LIBRARY_SERVER_KMIPv14 0x00000080 1.4 + SYMMETRIC_KEY_LIFECYCLE_CLIENT_KMIPv14 0x00000081 1.4 + SYMMETRIC_KEY_LIFECYCLE_SERVER_KMIPv14 0x00000082 1.4 + ASYMMETRIC_KEY_LIFECYCLE_CLIENT_KMIPv14 0x00000083 1.4 + ASYMMETRIC_KEY_LIFECYCLE_SERVER_KMIPv14 0x00000084 1.4 + BASIC_CRYPTOGRAPHIC_CLIENT_KMIPv14 0x00000085 1.4 + BASIC_CRYPTOGRAPHIC_SERVER_KMIPv14 0x00000086 1.4 + ADVANCED_CRYPTOGRAPHIC_CLIENT_KMIPv14 0x00000087 1.4 + ADVANCED_CRYPTOGRAPHIC_SERVER_KMIPv14 0x00000088 1.4 + RNG_CRYPTOGRAPHIC_CLIENT_KMIPv14 0x00000089 1.4 + RNG_CRYPTOGRAPHIC_SERVER_KMIPv14 0x0000008a 1.4 + BASIC_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv14 0x0000008b 1.4 + INTERMEDIATE_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv14 0x0000008c 1.4 + ADVANCED_SYMMETRIC_KEY_FOUNDRY_CLIENT_KMIPv14 0x0000008d 1.4 + SYMMETRIC_KEY_FOUNDRY_SERVER_KMIPv14 0x0000008e 1.4 + OPAQUE_MANAGED_OBJECT_STORE_CLIENT_KMIPv14 0x0000008f 1.4 + OPAQUE_MANAGED_OBJECT_STORE_SERVER_KMIPv14 0x00000090 1.4 + SUITE_B_MINLOS_128_CLIENT_KMIPv14 0x00000091 1.4 + SUITE_B_MINLOS_128_SERVER_KMIPv14 0x00000092 1.4 + SUITE_B_MINLOS_192_CLIENT_KMIPv14 0x00000093 1.4 + SUITE_B_MINLOS_192_SERVER_KMIPv14 0x00000094 1.4 + STORAGE_ARRAY_WITH_SELF_ENCRYPTING_DRIVE_CLIENT_KMIPv14 0x00000095 1.4 + STORAGE_ARRAY_WITH_SELF_ENCRYPTING_DRIVE_SERVER_KMIPv14 0x00000096 1.4 + HTTPS_CLIENT_KMIPv14 0x00000097 1.4 + HTTPS_SERVER_KMIPv14 0x00000098 1.4 + JSON_CLIENT_KMIPv14 0x00000099 1.4 + JSON_SERVER_KMIPv14 0x0000009a 1.4 + XML_CLIENT_KMIPv14 0x0000009b 1.4 + XML_SERVER_KMIPv14 0x0000009c 1.4 + ======================================================= ========== ============ + + profile_information + (dict) (1.3) A dictionary containing information about a KMIP profile + supported by a KMIP server. Often obtained from the Query operation + response. + + >>> from kmip import enums + >>> profile_information = { + ... 'profile_name': enums.ProfileName.BASELINE_SERVER_BASIC_KMIPv12, + ... 'server_uri': 'https://127.0.0.1', + ... 'server_port': 5696 + ... } + + ==================== ======= ============ + Key Value KMIP Version + ==================== ======= ============ + :term:`profile_name` enum 1.3 + server_uri string 1.3 + server_port int 1.3 + ==================== ======= ============ + + put_function + (enum) (1.0) An enumeration specifying the state of an object being + pushed by the Put operation. + + >>> from kmip import enums + >>> enums.PutFunction.NEW + + + ======= ========== ============ + Name Value KMIP Version + ======= ========== ============ + NEW 0x00000001 1.0 + REPLACE 0x00000002 1.0 + ======= ========== ============ + + query_function + (enum) (1.0) An enumeration specifying the information to include in + a Query operation response. + + >>> from kmip import enums + >>> enums.QueryFunction.QUERY_OPERATIONS + + + ================================= ========== ============ + Name Value KMIP Version + ================================= ========== ============ + QUERY_OPERATIONS 0x00000001 1.0 + QUERY_OBJECTS 0x00000002 1.0 + QUERY_SERVER_INFORMATION 0x00000003 1.0 + QUERY_APPLICATION_NAMESPACES 0x00000004 1.0 + QUERY_EXTENSION_LIST 0x00000005 1.1 + QUERY_EXTENSION_MAP 0x00000006 1.1 + QUERY_ATTESTATION_TYPES 0x00000007 1.2 + QUERY_RNGS 0x00000008 1.3 + QUERY_VALIDATIONS 0x00000009 1.3 + QUERY_PROFILES 0x0000000a 1.3 + QUERY_CAPABILITIES 0x0000000b 1.3 + QUERY_CLIENT_REGISTRATION_METHODS 0x0000000c 1.3 + ================================= ========== ============ + + recommended_curve + (enum) (1.0) An enumeration specifying a recommended curve for an + elliptic curve algorithm. Used often as an asymmetric key value + attribute. + + >>> from kmip import enums + >>> enums.RecommendedCurve.P_192 + + + ================ ========== ============ + Name Value KMIP Version + ================ ========== ============ + P_192 0x00000001 1.0 + K_163 0x00000002 1.0 + B_163 0x00000003 1.0 + P_224 0x00000004 1.0 + K_233 0x00000005 1.0 + B_233 0x00000006 1.0 + P_256 0x00000007 1.0 + K_283 0x00000008 1.0 + B_283 0x00000009 1.0 + P_384 0x0000000a 1.0 + K_409 0x0000000b 1.0 + B_409 0x0000000c 1.0 + P_521 0x0000000d 1.0 + K_571 0x0000000e 1.0 + B_571 0x0000000f 1.0 + SECP112R1 0x00000010 1.2 + SECP112R2 0x00000011 1.2 + SECP128R1 0x00000012 1.2 + SECP128R2 0x00000013 1.2 + SECP160K1 0x00000014 1.2 + SECP160R1 0x00000015 1.2 + SECP160R2 0x00000016 1.2 + SECP191K1 0x00000017 1.2 + SECP224K1 0x00000018 1.2 + SECP256K1 0x00000019 1.2 + SECT113R1 0x0000001a 1.2 + SECT113R2 0x0000001b 1.2 + SECT131R1 0x0000001c 1.2 + SECT131R2 0x0000001d 1.2 + SECT163R1 0x0000001e 1.2 + SECT193R1 0x0000001f 1.2 + SECT193R2 0x00000020 1.2 + SECT239K1 0x00000021 1.2 + ANSIX9P192V2 0x00000022 1.2 + ANSIX9P192V3 0x00000023 1.2 + ANSIX9P239V1 0x00000024 1.2 + ANSIX9P239V2 0x00000025 1.2 + ANSIX9P239V3 0x00000026 1.2 + ANSIX9C2PNB163V1 0x00000027 1.2 + ANSIX9C2PNB163V2 0x00000028 1.2 + ANSIX9C2PNB163V3 0x00000029 1.2 + ANSIX9C2PNB176V1 0x0000002a 1.2 + ANSIX9C2TNB191V1 0x0000002b 1.2 + ANSIX9C2TNB191V2 0x0000002c 1.2 + ANSIX9C2TNB191V3 0x0000002d 1.2 + ANSIX9C2PNB208W1 0x0000002e 1.2 + ANSIX9C2TNB239V1 0x0000002f 1.2 + ANSIX9C2TNB239V2 0x00000030 1.2 + ANSIX9C2TNB239V3 0x00000031 1.2 + ANSIX9C2PNB272W1 0x00000032 1.2 + ANSIX9C2PNB304W1 0x00000033 1.2 + ANSIX9C2TNB359V1 0x00000034 1.2 + ANSIX9C2PNB368W1 0x00000035 1.2 + ANSIX9C2TNB431R1 0x00000036 1.2 + BRAINPOOLP160R1 0x00000037 1.2 + BRAINPOOLP160T1 0x00000038 1.2 + BRAINPOOLP192R1 0x00000039 1.2 + BRAINPOOLP192T1 0x0000003a 1.2 + BRAINPOOLP224R1 0x0000003b 1.2 + BRAINPOOLP224T1 0x0000003c 1.2 + BRAINPOOLP256R1 0x0000003d 1.2 + BRAINPOOLP256T1 0x0000003e 1.2 + BRAINPOOLP320R1 0x0000003f 1.2 + BRAINPOOLP320T1 0x00000040 1.2 + BRAINPOOLP384R1 0x00000041 1.2 + BRAINPOOLP384T1 0x00000042 1.2 + BRAINPOOLP512R1 0x00000043 1.2 + BRAINPOOLP512T1 0x00000044 1.2 + ================ ========== ============ + + result_reason + (enum) (1.0) An enumeration specifying the reason for the result + status of an operation. Used usually if an operation results in a + failure. + + >>> from kmip import enums + >>> enums.ResultReason.ITEM_NOT_FOUND + + + =================================== ========== ============ + Name Value KMIP Version + =================================== ========== ============ + ITEM_NOT_FOUND 0x00000001 1.0 + RESPONSE_TOO_LARGE 0x00000002 1.0 + AUTHENTICATION_NOT_SUCCESSFUL 0x00000003 1.0 + INVALID_MESSAGE 0x00000004 1.0 + OPERATION_NOT_SUPPORTED 0x00000005 1.0 + MISSING_DATA 0x00000006 1.0 + INVALID_FIELD 0x00000007 1.0 + FEATURE_NOT_SUPPORTED 0x00000008 1.0 + OPERATION_CANCELED_BY_REQUESTER 0x00000009 1.0 + CRYPTOGRAPHIC_FAILURE 0x0000000a 1.0 + ILLEGAL_OPERATION 0x0000000b 1.0 + PERMISSION_DENIED 0x0000000c 1.0 + OBJECT_ARCHIVED 0x0000000d 1.0 + INDEX_OUT_OF_BOUNDS 0x0000000e 1.0 + APPLICATION_NAMESPACE_NOT_SUPPORTED 0x0000000f 1.0 + KEY_FORMAT_TYPE_NOT_SUPPORTED 0x00000010 1.0 + KEY_COMPRESSION_TYPE_NOT_SUPPORTED 0x00000011 1.0 + ENCODING_OPTION_ERROR 0x00000012 1.1 + KEY_VALUE_NOT_PRESENT 0x00000013 1.2 + ATTESTATION_REQUIRED 0x00000014 1.2 + ATTESTATION_FAILED 0x00000015 1.2 + SENSITIVE 0x00000016 1.4 + NOT_EXTRACTABLE 0x00000017 1.4 + OBJECT_ALREADY_EXISTS 0x00000018 1.4 + GENERAL_FAILURE 0x00000100 1.0 + =================================== ========== ============ + + result_status + (enum) (1.0) An enumeration specifying the result of an operation. + Used in every operation response. + + >>> from kmip import enums + >>> enums.ResultStatus.OPERATION_FAILED + + + ================= ========== ============ + Name Value KMIP Version + ================= ========== ============ + SUCCESS 0x00000000 1.0 + OPERATION_FAILED 0x00000001 1.0 + OPERATION_PENDING 0x00000002 1.0 + OPERATION_UNDONE 0x00000003 1.0 + ================= ========== ============ + + revocation_reason_code + (enum) (1.0) An enumeration specifying the reason for the revocation + of a managed object. + + >>> from kmip import enums + >>> enums.RevocationReasonCode.KEY_COMPROMISE + + + ====================== ========== ============ + Name Value KMIP Version + ====================== ========== ============ + UNSPECIFIED 0x00000001 1.0 + KEY_COMPROMISE 0x00000002 1.0 + CA_COMPROMISE 0x00000003 1.0 + AFFILIATION_CHANGED 0x00000004 1.0 + SUPERSEDED 0x00000005 1.0 + CESSATION_OF_OPERATION 0x00000006 1.0 + PRIVILEGE_WITHDRAWN 0x00000007 1.0 + ====================== ========== ============ + + rng_algorithm + (enum) (1.3) An enumeration specifying an algorithm for random number + generation. Used often to describe a random number generator. + + >>> from kmip import enums + >>> enums.RNGAlgorithm.DRBG + + + =========== ========== ============ + Name Value KMIP Version + =========== ========== ============ + UNSPECIFIED 0x00000001 1.3 + FIPS186_2 0x00000002 1.3 + DRBG 0x00000003 1.3 + NRBG 0x00000004 1.3 + ANSI_X931 0x00000005 1.3 + ANSI_X962 0x00000006 1.3 + =========== ========== ============ + + rng_mode + (enum) (1.3) An enumeration specifying the mode for random number + generation. Used often to describe a random number generator. + + >>> from kmip import enums + >>> enums.RNGMode.SHARED_INSTANTIATION + + + ======================== ========== ============ + Name Value KMIP Version + ======================== ========== ============ + UNSPECIFIED 0x00000001 1.3 + SHARED_INSTANTIATION 0x00000002 1.3 + NON_SHARED_INSTANTIATION 0x00000003 1.3 + ======================== ========== ============ + + rng_parameters + (dict) (1.3) A dictionary containing information about a random + number generator supported by a KMIP server. Often obtained from the + Query operation response. + + >>> from kmip import enums + >>> rng_parameters = { + ... 'rng_algorithm': enums.RNGAlgorithm.ANSI_X931, + ... 'cryptographic_algorithm': enums.CryptographicAlgorithm.AES, + ... 'cryptographic_length': 256, + ... 'hashing_algorithm': enums.HashingAlgorithm.SHA_256, + ... 'drbg_algorithm': enums.DRBGAlgorithm.HASH, + ... 'recommended_curve': enums.RecommendedCurve.B_163, + ... 'fips186_variation': enums.FIPS186Variation.X_ORIGINAL, + ... 'prediction_resistance': True + ... } + + =============================== ======= ============ + Key Value KMIP Version + =============================== ======= ============ + :term:`rng_algorithm` enum 1.3 + :term:`cryptographic_algorithm` enum 1.3 + :term:`cryptographic_length` int 1.3 + :term:`hashing_algorithm` enum 1.3 + :term:`drbg_algorithm` enum 1.3 + :term:`recommended_curve` enum 1.3 + :term:`fips186_variation` enum 1.3 + prediction_resistance bool 1.3 + =============================== ======= ============ + + secret_data_type + (enum) (1.0) An enumeration specifying the type of a secret data + object. + + >>> from kmip import enums + >>> enums.SecretDataType.PASSWORD + + + ======== ========== ============ + Name Value KMIP Version + ======== ========== ============ + PASSWORD 0x00000001 1.0 + SEED 0x00000002 1.0 + ======== ========== ============ + + server_information + (str) (1.0) A string containing additional information on the vendor + associated with a KMIP appliance. Often obtained with the Query + operation. + + shredding_algorithm + (enum) (1.3) An enumeration specifying the type of shredding + algorithm supported by a key server. Used often as part of the + response to a Query request. + + >>> from kmip import enums + >>> enums.ShreddingAlgorithm.CRYPTOGRAPHIC + + + ============= ========== ============ + Name Value KMIP Version + ============= ========== ============ + UNSPECIFIED 0x00000001 1.3 + CRYPTOGRAPHIC 0x00000002 1.3 + UNSUPPORTED 0x00000003 1.3 + ============= ========== ============ + + split_key_method + (enum) (1.0) An enumeration specifying the method used to split a key. + Used as an attribute for split key objects and as a parameter to the + CreateSplitKey operation. + + >>> from kmip import enums + >>> enums.SplitKeyMethod.XOR + + + ============================== ========== ============ + Name Value KMIP Version + ============================== ========== ============ + XOR 0x00000001 1.0 + POLYNOMIAL_SHARING_GF_2_16 0x00000002 1.0 + POLYNOMIAL_SHARING_PRIME_FIELD 0x00000003 1.0 + POLYNOMIAL_SHARING_GF_2_8 0x00000004 1.2 + ============================== ========== ============ + + state + (enum) (1.0) An enumeration specifying the state of a managed object. + Used as an attribute for every managed object on a key server. + + >>> from kmip import enums + >>> enums.State.ACTIVE + + + ===================== ========== ============ + Name Value KMIP Version + ===================== ========== ============ + PRE_ACTIVE 0x00000001 1.0 + ACTIVE 0x00000002 1.0 + DEACTIVATED 0x00000003 1.0 + COMPROMISED 0x00000004 1.0 + DESTROYED 0x00000005 1.0 + DESTROYED_COMPROMISED 0x00000006 1.0 + ===================== ========== ============ + + storage_status + (enum) (1.0) An enumeration specifying the state of a stored object. + Used as a filter for the Locate operation. + + >>> from kmip import enums + >>> enums.StorageStatus.ARCHIVAL_STORAGE + + + ================ ========== ============ + Name Value KMIP Version + ================ ========== ============ + ONLINE_STORAGE 0x00000001 1.0 + ARCHIVAL_STORAGE 0x00000002 1.0 + ================ ========== ============ + + unique_identifier + (str) (1.0) A string representing a unique, global identifier for a + managed object created or registered with a key management appliance. + Each managed object is represented by one unique identifier, which + can be used in a variety of operations to access the object or the + object metadata. This identifier is assigned when the object is first + created or registered and cannot be changed. + + unwrap_mode + (enum) (1.3) An enumeration specifying an unwrapping mode supported + by the server. Used often as part of the response to a Query + request. + + >>> from kmip import enums + >>> enums.UnwrapMode.PROCESSED + + + ============= ========== ============ + Name Value KMIP Version + ============= ========== ============ + UNSPECIFIED 0x00000001 1.3 + PROCESSED 0x00000002 1.3 + NOT_PROCESSED 0x00000003 1.3 + ============= ========== ============ + + usage_limits_unit + (enum) (1.0) An enumeration specifying the units for a usage limit on + a managed object. + + >>> from kmip import enums + >>> enums.UsageLimitsUnit.BYTE + + + ====== ========== ============ + Name Value KMIP Version + ====== ========== ============ + BYTE 0x00000001 1.0 + OBJECT 0x00000002 1.0 + ====== ========== ============ + + validation_authority_type + (enum) (1.3) An enumeration specifying a validation authority type + supported by the server. Used often as part of the response to a + Query request. + + >>> from kmip import enums + >>> enums.ValidationAuthorityType.COMMON_CRITERIA + + + =============== ========== ============ + Name Value KMIP Version + =============== ========== ============ + UNSPECIFIED 0x00000001 1.3 + NIST_CMVP 0x00000002 1.3 + COMMON_CRITERIA 0x00000003 1.3 + =============== ========== ============ + + validation_information + (dict) (1.3) A dictionary containing information about a formal + validation. Often obtained from the Query operation response. + + >>> from kmip import enums + >>> validation_information = { + ... 'validation_authority_type': enums.ValidationAuthorityType.COMMON_CRITERIA, + ... 'validation_authority_country': 'US', + ... 'validation_profile': [ + ... 'Example Profile 1', + ... 'Example Profile 2' + ... ] + ... } + + ================================= ======= ============ + Key Value KMIP Version + ================================= ======= ============ + :term:`validation_authority_type` enum 1.3 + validation_authority_country string 1.3 + validation_authority_uri string 1.3 + validation_version_major int 1.3 + validation_version_minor int 1.3 + :term:`validation_type` enum 1.3 + validation_level int 1.3 + validation_certificate_identifier string 1.3 + validation_certificate_uri string 1.3 + validation_vendor_uri string 1.3 + validation_profile list 1.3 + ================================= ======= ============ + + validation_type + (enum) (1.3) An enumeration specifying a validation type supported by + the server. Used often as part of the response to a Query request. + + >>> from kmip import enums + >>> enums.ValidationType.HARDWARE + + + =========== ========== ============ + Name Value KMIP Version + =========== ========== ============ + UNSPECIFIED 0x00000001 1.3 + HARDWARE 0x00000002 1.3 + SOFTWARE 0x00000003 1.3 + FIRMWARE 0x00000004 1.3 + HYBRID 0x00000005 1.3 + =========== ========== ============ + + validity_indicator + (enum) (1.0) An enumeration specifying the validity of an operation or + object. Used as a return value for various operations. + + >>> from kmip import enums + >>> enums.ValidityIndicator.VALID + + + ======= ========== ============ + Name Value KMIP Version + ======= ========== ============ + VALID 0x00000001 1.0 + INVALID 0x00000002 1.0 + UNKNOWN 0x00000003 1.0 + ======= ========== ============ + + vendor_identification + (str) (1.0) A string containing identification information on the + vendor associated with a KMIP appliance. Often obtained with the Query + operation. + + wrapping_method + (enum) (1.0) An enumeration representing a key wrapping mechanism. + Used in various key wrapping metadata structures. + + >>> from kmip import enums + >>> enums.WrappingMethod.ENCRYPT + + + ===================== ========== ============ + Name Value KMIP Version + ===================== ========== ============ + ENCRYPT 0x00000001 1.0 + MAC_SIGN 0x00000002 1.0 + ENCRYPT_THEN_MAC_SIGN 0x00000003 1.0 + MAC_SIGN_THEN_ENCRYPT 0x00000004 1.0 + TR_31 0x00000005 1.0 + ===================== ========== ============ diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..8774ea0 --- /dev/null +++ b/docs/source/index.rst @@ -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 ` 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/ diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..82f6043 --- /dev/null +++ b/docs/source/installation.rst @@ -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 diff --git a/docs/source/server.rst b/docs/source/server.rst new file mode 100644 index 0000000..aa1ab5b --- /dev/null +++ b/docs/source/server.rst @@ -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 ` 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 ` 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 diff --git a/tox.ini b/tox.ini index 5a839d1..ff91c48 100644 --- a/tox.ini +++ b/tox.ini @@ -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