|
| 1 | +The "kmipclient" library |
| 2 | +-- |
| 3 | +KMIP client is the C++ library that allows simple access to the KMIP servers using the KMIP protocol. |
| 4 | + |
| 5 | +The "kmipclient" library wraps up the low-level libkmip (kmip.h, kmip.c) into C++ code. |
| 6 | +The purpose of such wrap-up is to: |
| 7 | + |
| 8 | +## Design goals. |
| 9 | + |
| 10 | +1. Provide easy to use and hard to misuse interface with forced error processing. |
| 11 | +2. Hide low-level details. |
| 12 | +3. Minimize manual memory management |
| 13 | +4. Make the library easy to extend |
| 14 | +5. Exclude mid-level (kmip_bio.c), use the low-level (kmip.c) only |
| 15 | +6. Easy to replace network communication level |
| 16 | +7. Testability |
| 17 | + |
| 18 | +## External dependencies |
| 19 | + |
| 20 | +No extra external dependencies should be used, except existing OpenSSL dependency. |
| 21 | +KmipClient itself does not depend on any library except "kmip". The network communication level is injected |
| 22 | +into KmipClient instance as implementation of the NetClient interface. The library has ready to use |
| 23 | +OpenSSL BIO based implementation called NetClientOpenSSL. User of the library can use any other library to |
| 24 | +implement the communication level. |
| 25 | + |
| 26 | +## High level design |
| 27 | + |
| 28 | +The top interface wraps network communication level (based on OpenSSL) and the KMIP protocol encoding level. |
| 29 | +It is implemented as header-only class in the file “Kmip.hpp” and can be used similar to the old C++ wrapper |
| 30 | +(kmippp.h). Actual high level interface consists of two headers: NetClient.hpp. and KmipClient.hpp. |
| 31 | + |
| 32 | +The first interface is just a contract to wrap low-level network communications similar to well-known |
| 33 | +interfaces (socket, OpenSSL bio and others). It contains 4 methods only: connect(), close(), send() |
| 34 | +and receive(). This interface also has an implementation, declared “NetClientOpenSSL.hpp”. |
| 35 | +It is based on OpenSSL BIO functions. |
| 36 | + |
| 37 | +The second interface is actual KMIP protocol implementation. It requires a NetClient implementation |
| 38 | +as a dependency injection in the constructor. This interface is also similar to the existing C++ wrapper |
| 39 | +and can be used the similar whay when properly initialized with the NetClient-derived instance. |
| 40 | + |
| 41 | +The main difference to the “kmippp.h” is in-band error processing. It uses a template similar to |
| 42 | +std::expected from the C++ 23. Though, project may use older C++ standard (C++ 20), so the interface |
| 43 | +includes a C++ 20 implementation, that wraps standard implementation or provides replacement if it is absent. |
| 44 | + |
| 45 | +All KMIP request creation and encoding are encapsulated in the RequestFactory class. All operations are |
| 46 | +on stack and do not require memory management. |
| 47 | + |
| 48 | +All KMIP responses processing are encapsulated in ResponseFactory class. It should be operated on stack |
| 49 | +to keep data in place. Copy and move operations are disabled. |
| 50 | + |
| 51 | +By the protocol, parsed response contains one or more response batch items. To process these items, |
| 52 | +ResponseFactory class is used. It’s purpose is to extract values from the response batch item. V |
| 53 | +alues are keys, secrets, attributes, etc. This class does not have a state and consists of static methods. |
| 54 | + |
| 55 | +All operation in the low-level KMIP library are based on context structure KMIP. This structure is |
| 56 | +encapsulated in KmipCtx class along with operations on buffers, errors, etc. This class, once created, |
| 57 | +is passed by the reference to other classes of the “kmipclient” library. Copy and move operations are |
| 58 | +disabled for this class also. Usually, the instance of this class is created on stack in the high-level |
| 59 | +methods and does not require memory management. |
| 60 | + |
| 61 | +The high-level interface usage example: |
| 62 | + |
| 63 | +```C++ |
| 64 | +NetClientOpenSSL net_client (argv[1], argv[2], argv[3], argv[4], argv[5], 200); |
| 65 | +KmipClient client (net_client); |
| 66 | + |
| 67 | + const auto opt_key = client.op_get_key (argv[6]); |
| 68 | + if (opt_key.has_value ()) |
| 69 | + { |
| 70 | + std::cout << "Key: 0x"; |
| 71 | + auto k = opt_key.value (); |
| 72 | + print_hex (k.value()); |
| 73 | + } |
| 74 | + else |
| 75 | + { |
| 76 | + std::cerr << "Can not get key with id:"<< argv[6] << " Cause: "<< opt_key.error().message << std::endl; |
| 77 | + }; |
| 78 | +``` |
| 79 | +As can be seen from the code above, the NetClientOpenSSL class instance is injected as dependency |
| 80 | +inversion into the KmipClient class instance. This approach allows to use any net connection with KmipClient. |
| 81 | +It is enough to derive the class from NetClient class and wrap 4 calls. |
| 82 | +
|
| 83 | +To understand, how to extend functionality, below is example of request creation: |
| 84 | +
|
| 85 | +```C++ |
| 86 | +void |
| 87 | +RequestFactory::create_get_rq (KmipCtx &ctx, const id_t &id) |
| 88 | +{ |
| 89 | + KmipRequest rq (ctx); |
| 90 | + TextString uuid = {}; |
| 91 | + uuid.size = id.size (); |
| 92 | + uuid.value = const_cast<char *>(id.c_str ()); |
| 93 | +
|
| 94 | + GetRequestPayload grp {}; |
| 95 | + grp.unique_identifier = &uuid; |
| 96 | +
|
| 97 | + RequestBatchItem rbi {}; |
| 98 | + kmip_init_request_batch_item (&rbi); |
| 99 | + rbi.operation = KMIP_OP_GET; |
| 100 | + rbi.request_payload = &grp; |
| 101 | + rq.set_batch_item (&rbi); |
| 102 | + rq.encode (); |
| 103 | +} |
| 104 | +``` |
| 105 | +In the example above we use low-level primitives from “kmip.h” to create the RequestBatchItem and |
| 106 | +then we add it to the internal member of “KmipRequest” class, which performs appropriate |
| 107 | +request encoding in to the KMIP context. |
| 108 | + |
| 109 | +Below is an example of the response processing: |
| 110 | + |
| 111 | +```C++ |
| 112 | +ve::expected<Key, Error> |
| 113 | +ResponseResultFactory::get_key (ResponseBatchItem *rbi) |
| 114 | +{ |
| 115 | + auto *pld = static_cast<GetResponsePayload *> (rbi->response_payload); |
| 116 | + switch (pld->object_type) |
| 117 | + { |
| 118 | + //name known key to KeyFactory types |
| 119 | + case KMIP_OBJTYPE_SYMMETRIC_KEY: |
| 120 | + KMIP_OBJTYPE_PUBLIC_KEY: |
| 121 | + KMIP_OBJTYPE_PRIVATE_KEY: |
| 122 | + KMIP_OBJTYPE_CERTIFICATE: |
| 123 | + { |
| 124 | + return KeyFactory::parse_response(pld); |
| 125 | + }; |
| 126 | + default: |
| 127 | + return Error(-1,"Invalid response object type."); |
| 128 | + } |
| 129 | +} |
| 130 | + |
| 131 | +``` |
| 132 | +And here is an example of top-level function implementation |
| 133 | +
|
| 134 | +```C++ |
| 135 | +my::expected<Key, Error> |
| 136 | +KmipClient::op_get_key (const id_t &id) |
| 137 | +{ |
| 138 | + KmipCtx ctx; |
| 139 | + RequestFactory request_factory(ctx); |
| 140 | + ResponseFactory rf(ctx); |
| 141 | + try |
| 142 | + { |
| 143 | + request_factory.create_get_rq (id); |
| 144 | + io->do_exchange (ctx); |
| 145 | + return rf.get_key(0); |
| 146 | + } |
| 147 | + catch (ErrorException &e) |
| 148 | + { |
| 149 | + return Error(e.code (), e.what ()); |
| 150 | + } |
| 151 | +} |
| 152 | +``` |
| 153 | +As can be seen from the source code, each KMIP low-level entity is encapsulated in some C++ class, |
| 154 | +therefore advanced C++ memory management is utilized. Also, the design is avoiding any kind |
| 155 | +of smart pointers (almost… sometimes we need it), utilizing on-stack variables. Raw pointers from |
| 156 | +the low-level code are used rarely just to pass stack-based data for more detailed processing. |
| 157 | + |
| 158 | +It is worth of mentioning, that KMIP protocol supports multiple request items ( batch items ) |
| 159 | +in one network request. For example, it might be combination of GET and GET_ATTRRIBUTE operations |
| 160 | +to have a key with set of it’s attributes. It is important to have key state attribute, |
| 161 | +because a key could be outdated, deactivated or marked as compromised. |
| 162 | + |
| 163 | +The design of this library supports multiple batch items in requests and in responses. |
| 164 | + |
| 165 | +## Usage |
| 166 | + |
| 167 | +Please, seee usage examples in the "examples" directory |
| 168 | + |
0 commit comments