ceph/src/libkmip/docs/source/examples.rst

   1 Examples
   2 ========
   3 To demonstrate how to use libkmip, several example applications are built
   4 and deployed with the library to get developers started.
   5
   6 Demos
   7 -----
   8 Three demo applications are included with libkmip, one for each of the
   9 following KMIP operations:
  10
  11 * ``Create``
  12 * ``Get``
  13 * ``Destroy``
  14
  15 If libkmip is built, the demo applications can be found in the local build
  16 directory. If libkmip is installed, the demo applications can also be found
  17 in the bin directory, by default located at ``/usr/local/bin/kmip``.
  18
  19 Run any of the demo applications with the ``-h`` flag to see usage
  20 information.
  21
  22 Create Demo
  23 ~~~~~~~~~~~
  24 The ``Create`` demo, ``demo_create.c``, uses the :ref:`low-level-api` to issue
  25 a KMIP request to the KMIP server to create a symmetric key. The application
  26 manually creates the library context and initalizes it. It then manually
  27 builds the request message structure, creating the following attributes for
  28 the symmetric key:
  29
  30 * cryptographic algorithm (AES)
  31 * cryptographic length (256 bits)
  32 * cryptographic usage mask (Encrypt and Decrypt usage)
  33
  34 The demo application encodes the request and then sends it through the
  35 low-level API to retrieve the response encoding. It decodes the response
  36 encoding into the response message structure and then extracts the UUID of
  37 the newly created symmetric key.
  38
  39 Get Demo
  40 ~~~~~~~~
  41 The ``Get`` demo, ``demo_get.c``, uses the :ref:`mid-level-api` to issue a
  42 KMIP request to the KMIP server to retrieve a symmetric key. The application
  43 manually creates the library context and initializes it. It sets its own
  44 custom memory handlers to override the default ones supplied by libkmip and
  45 then invokes the mid-level API with the UUID of the symmetric key it wants
  46 to retrieve.
  47
  48 The client API internally builds the corresponding request message, encodes
  49 it, sends it via BIO to the KMIP server, retrieves the response encoding, and
  50 then decodes the response into the corresponding response message structure.
  51 Finally, it extracts the symmetric key bytes and copies them to a separate
  52 block of memory that will be handed back to the demo application. Finally, it
  53 cleans up the buffers used for the encoding and decoding process and cleans
  54 up the response message structure.
  55
  56 Destroy Demo
  57 ~~~~~~~~~~~~
  58 The ``Destroy`` demo, ``demo_destroy.c``, use the :ref:`high-level-api` to
  59 issue a KMIP request to the KMIP server to destroy a symmetric key. The
  60 application invokes the high-level API with the UUID of the symmetric key it
  61 wants to destroy.
  62
  63 The client API internally builds the library context along with the
  64 corresponding request message. It encodes the request, sends it via BIO to
  65 the KMIP server, retrieves the response encoding, and then decodes the
  66 response into the corresponding response message structure. Finally, it
  67 extracts the result of the KMIP operation from the response message structure
  68 and returns it.
  69
  70 Tests
  71 -----
  72 A test application is also included with libkmip to exercise the encoding and
  73 decoding capabilities for all support KMIP features. The source code for this
  74 application, ``tests.c``, contains numerous examples of how to build and use
  75 different libkmip structures.
  76