diff options
Diffstat (limited to '')
| -rw-r--r-- | src/libkmip/docs/source/examples.rst | 76 |
1 files changed, 76 insertions, 0 deletions
diff --git a/src/libkmip/docs/source/examples.rst b/src/libkmip/docs/source/examples.rst new file mode 100644 index 000000000..89cbac45d --- /dev/null +++ b/src/libkmip/docs/source/examples.rst @@ -0,0 +1,76 @@ +Examples +======== +To demonstrate how to use libkmip, several example applications are built +and deployed with the library to get developers started. + +Demos +----- +Three demo applications are included with libkmip, one for each of the +following KMIP operations: + +* ``Create`` +* ``Get`` +* ``Destroy`` + +If libkmip is built, the demo applications can be found in the local build +directory. If libkmip is installed, the demo applications can also be found +in the bin directory, by default located at ``/usr/local/bin/kmip``. + +Run any of the demo applications with the ``-h`` flag to see usage +information. + +Create Demo +~~~~~~~~~~~ +The ``Create`` demo, ``demo_create.c``, uses the :ref:`low-level-api` to issue +a KMIP request to the KMIP server to create a symmetric key. The application +manually creates the library context and initalizes it. It then manually +builds the request message structure, creating the following attributes for +the symmetric key: + +* cryptographic algorithm (AES) +* cryptographic length (256 bits) +* cryptographic usage mask (Encrypt and Decrypt usage) + +The demo application encodes the request and then sends it through the +low-level API to retrieve the response encoding. It decodes the response +encoding into the response message structure and then extracts the UUID of +the newly created symmetric key. + +Get Demo +~~~~~~~~ +The ``Get`` demo, ``demo_get.c``, uses the :ref:`mid-level-api` to issue a +KMIP request to the KMIP server to retrieve a symmetric key. The application +manually creates the library context and initializes it. It sets its own +custom memory handlers to override the default ones supplied by libkmip and +then invokes the mid-level API with the UUID of the symmetric key it wants +to retrieve. + +The client API internally builds the corresponding request message, encodes +it, sends it via BIO to the KMIP server, retrieves the response encoding, and +then decodes the response into the corresponding response message structure. +Finally, it extracts the symmetric key bytes and copies them to a separate +block of memory that will be handed back to the demo application. Finally, it +cleans up the buffers used for the encoding and decoding process and cleans +up the response message structure. + +Destroy Demo +~~~~~~~~~~~~ +The ``Destroy`` demo, ``demo_destroy.c``, use the :ref:`high-level-api` to +issue a KMIP request to the KMIP server to destroy a symmetric key. The +application invokes the high-level API with the UUID of the symmetric key it +wants to destroy. + +The client API internally builds the library context along with the +corresponding request message. It encodes the request, sends it via BIO to +the KMIP server, retrieves the response encoding, and then decodes the +response into the corresponding response message structure. Finally, it +extracts the result of the KMIP operation from the response message structure +and returns it. + +Tests +----- +A test application is also included with libkmip to exercise the encoding and +decoding capabilities for all support KMIP features. The source code for this +application, ``tests.c``, contains numerous examples of how to build and use +different libkmip structures. + |