KMIPClient Component

Properties   Methods   Events   Config Settings   Errors  

The KMIPClient component provides client-side functionality for KMIP protocol.

Syntax

TsbxKMIPClient

Remarks

The KMIPClient component implements the client-side counterpart of the KMIP environment. KMIP, or the Key Management Interoperability Protocol, is an OASIS standard of communication between applications that need to use or manage cryptographic keys over the network. A typical example of a KMIP client is an application that needs to access a remotely stored cryptographic key (shared by a KMIP server) - for example, to solicit a digital signature or decrypt an encrypted document.

Capabilities

KMIPClient supports the majority of the features defined by the KMIP specification, both on the key management and cryptographic operations fronts. While the KMIP version implemented in KMIPClient is 1.3, the KMIP approach to version sequencing allows KMIPClient to communicate equally efficiently with implementations supporting earlier and newer protocol versions. All the three encoding types (TTLV, JSON, and XML) are supported, which can be used over TCP, TLS, or HTTP(S) transports.

Working with KMIPClient

Setting up the component

KMIP servers can come in a variety of configurations, many of which cannot be detected or applied automatically. That's why the first stage is about configuring the component in such way that it knows how to talk to a specific server that you need to work with. Below are the key settings that you need to tune up. You can get most or all of this information from the administrator of the KMIP server:

Network access parameters

This is the network address and port that the KMIP server is listening on - for example, 10.0.1.110:5696 or kmip.server.com:25696.

The transport type

This could be one of TCP (unencrypted low-level connection), TLS (encrypted low-level connection), HTTP (unencrypted HTTP), HTTPS (encrypted HTTP). Transport type is not negotiable: the client must use exactly the same transport as the server expects. You specify the transport by applying the appropriate transport-specific prefix to the server address that you are passing to BaseURL:

• kmip:// for plain TCP (e.g. kmip://10.0.1.110:5696)
• kmips:// for TLS (e.g. kmips://kmip.server.com:25696)
• http:// for HTTP (e.g. http://kmip.server.com:80)
• https:// for HTTPS (e.g. https://10.0.1.110:5697)

KMIP servers accessible over HTTP(S) may reside either at a root (/) or a deeper-level web server endpoint (for example, /services/kmip). Append this path to the network parameters as you would normally do when working with HTTP endpoints. Having done that, combine the transport prefix, the network parameters, and the HTTP path (if used) together to obtain the value to assign to BaseURL:

client.BaseURL = "https://kmip.server.com:25696/services/kmip"; // TLS-secured HTTP connection to kmip.server.com running on port 25696

The encoding type

KMIP offers three encoding types: TTLV ("tag, type, length, value"), JSON, and XML. Depending on configuration and scenarios used installation may prefer one over the others. Plain TCP and TLS KMIP setups normally use TTLV encoding. The client and server must use the same encoding to understand each other.

TLS configuration

TLS-protected connections require additional setup of the TLS parameters. Those are not part of KMIP, but, rather, are intended to supply expected security configuration. The principal security setting here concerns the way the server's TLS certificate is validated. You will find more details about configuring TLS on the client side in the Validating TLS Certificates article.

Once the connection and protocol parameters are configured, you can go ahead and start making requests to the KMIP server. A KMIP server can serve requests which generally fall into one of the two categories:

• Key management requests - such as importing a certificate, generating a keypair, or obtaining a list of keys stored on the server.
• Cryptographic operation requests - such as signing or encrypting data.

Depending on your specific setup, the server may support a subset of operations from one or both categories.

Managing keys and certificates

The common key management operations are:

Importing a keypair or certificate to the server

Use AddKey to import an asymmetric keypair or its part, or a secret symmetric key, to the KMIP server. Use Add to import a certificate. Both methods return a unique object identifier that you can use to identify the object on the server.

Listing server objects

Use List to request a criteria-based list of objects from the server. The objects returned by the server will be published in the Objects collection.

Reading object properties

KMIPClient offers a few methods to read object properties. You can choose the method that fits your scenario best. Use Read and ReadKey methods to read certificates and keys directly into the Certificate and Key properties. You can then pass the received objects to other components that support them (such as CertificateManager). Use ReadObject to read the object into the Objects list. Use ReadAttribute to read a specific attribute of an object.

Generating server-side objects

KMIP supports server-side object generation, which allows for secure cryptographic material setup. Among objects you can generate are certificates (Generate) and generic keys (GenerateKey).

Making cryptographic calls

The common cryptographic calls are:

Signing data

Use the Sign method to sign the data using a server-side private key.

Encrypting and decrypting data

Use the Encrypt and Decrypt methods to encrypt or decrypt data using a server-side key. This method can be used with both symmetric and asymmetric keys.

Providing data for the operations

You can provide input for the cryptographic operations in one of the following forms:

• as a byte array - use InputBytes property.
• as a stream - use InputStream.
• in a file - use InputFile.

The processed (e.g. signed) data can be retrieved from an equivalent set of output properties (OutputBytes, OutputStream, OutputFile). You can mix and match input and output data sources as you need: for example, you can provide the input in a file, but read the output as a byte array from OutputBytes.

Note that the OutputBytes is only populated if neither of OutputFile and OutputStream is set.

Referencing server objects

Every object residing on a KMIP server is referenced by its unique object identifier. Your code is expected to pass the identifier of the object that you want to use or read to the relevant method, such as Sign or ReadObject. If you do not know the identifier of the object that you need to use, use the List method to solicit the list of the server-side objects first. Locate the required object in the list and pass its unique identifier to the needed method.

Property List

---

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

AuthTypes Property (KMIPClient Component)

Defines allowed HTTP authentication types.

Syntax

property AuthTypes: Integer read get_AuthTypes write set_AuthTypes;

Default Value

0

Remarks

Use this property to define which authentication types the component should support or attempt to use by enabling the relevant bitmask flags:

AuxResult Property (KMIPClient Component)

Contains the auxiliary result of the last performed operation.

Syntax

property AuxResult: String read get_AuxResult;

Default Value

''

Remarks

Use this property to obtain an auxiliary result of the last performed operation. One of such results is the new Counter/Nonce value after an encryption operation.

This property is read-only.

BaseURL Property (KMIPClient Component)

Specifies the url of the KMIP server.

Syntax

property BaseURL: String read get_BaseURL write set_BaseURL;

Default Value

''

Remarks

Use this property to specify the address of the KMIP server.

The address to assign to this property needs to be in the standard URI-like notation:

protocol://username:password@address:port/path

The protocol token must be based on the transport that you want to use (which is largely defined by the server setup) and can be one of the following:

• kmip:// - KMIP over TCP (unencrypted)
• kmips:// - KMIP over TLS (encrypted)
• http:// - KMIP over HTTP (unencrypted)
• https:// - KMIP over HTTPS (encrypted)

The address and port are network credentials that the server can be accessed at, such as 192.168.5.101:5696 for a server residing in a local network, or kmip.server.com:25696 for a server residing on the Internet. The path part can be used for KMIP servers accessible via HTTP(S) endpoints.

Examples

• kmip://10.25.0.61:5696
• kmips://10.0.1.10:11111
• kmips://kmip.server.com:11111
• http://user:password123@www.server.com:3128/services/kmip
• https://kmip.server.com:19991

Note that you need to take extra steps to prepare the component for secure connections when using TLS-enabled endpoints. One factor to be considered is the need to validate the server's TLS certificates. This article provides insights into the validation routine: Validating TLS Certificates.

The credentials used within the HTTP and HTTPS values are used for HTTP basic or digest authentication only. If your KMIP server expects you to use KMIP-level authentication, use Username and Password properties to provide your credentials.

BlockedCertificates Property (KMIPClient Component)

The certificates that must be rejected as trust anchors.

Syntax

property BlockedCertificates: TsbxCertificateList read get_BlockedCertificates write set_BlockedCertificates;

Remarks

Use this property to provide a list of compromised or blocked certificates. Any chain containing a blocked certificate will fail validation.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

Certificate Property (KMIPClient Component)

The certificate or request object to perform operations on.

Syntax

property Certificate: TsbxCertificate read get_Certificate write set_Certificate;

Remarks

Use this property to provide the certificate or CSR object on which a subsequent operation (such as Add or Generate) should be performed.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

ConnectionInfo Property (KMIPClient Component)

Returns the details of the underlying network connection.

Syntax

property ConnectionInfo: TsbxTLSConnectionInfo read get_ConnectionInfo;

Remarks

Use this property to learn about the connection setup, such as the protocol security details and amounts of data transferred each way.

This property is read-only and not available at design time.

Please refer to the TLSConnectionInfo type for a complete list of fields.

DataBytes Property (KMIPClient Component)

Use this property to pass the secondary input to the component in the byte array form.

Syntax

property DataBytes: TBytes read get_DataBytes write set_DataBytes;

Remarks

Some cryptographic operations require more than one inputs. One example is the Verify operation, which expects you to provide the signature and the data being authenticated as separate data pieces. This property lets you provide that secondary data piece (the data being authenticated). The primary data piece (the signature in this case) should be provided via one of the Input* properties, such as InputBytes.

This property is one of three ways in which you can provide the data to the component. The other two are DataFile and DataStream. Choose the data source type that fits your circumstances best.

This property is not available at design time.

DataFile Property (KMIPClient Component)

Use this property to pass the secondary input to the component from a file.

Syntax

property DataFile: String read get_DataFile write set_DataFile;

Default Value

''

Remarks

Some cryptographic operations require more than one inputs. One example is the Verify operation, which expects you to provide the signature and the data being authenticated as separate data pieces. This property lets you provide that secondary data piece (the data being authenticated). The primary data piece (the signature in this case) should be provided via one of the Input* properties, such as InputFile.

This property is one of three ways in which you can provide the data to the component. The other two are DataBytes and DataStream. Choose the data source type that fits your circumstances best.

Encoding Property (KMIPClient Component)

Specifies the KMIP encoding type.

Syntax

property Encoding: TsbxKMIPEncodings read get_Encoding write set_Encoding;

TsbxKMIPEncodings = (
  etTTLV,
  etXML,
  etJSON
);

Default Value

etTTLV

Remarks

Use this property to specify the KMIP message encoding to be used in the communications with the server.

The following encodings are available:

You need to know the right encoding for your KMIP server before accessing it. This is something you can get from the administrator of the server. KMIP servers accessible via plain TCP or TLS transports typically use the TTLV encoding.

ExternalCrypto Property (KMIPClient Component)

Provides access to external signing and DC parameters.

Syntax

property ExternalCrypto: TsbxExternalCrypto read get_ExternalCrypto;

Remarks

Use this property to tune-up remote cryptography settings. SecureBlackbox supports two independent types of external cryptography: synchronous (based on the ExternalSign event) and asynchronous (based on the DC protocol and the DCAuth signing component).

This property is read-only.

Please refer to the ExternalCrypto type for a complete list of fields.

FIPSMode Property (KMIPClient Component)

Reserved.

Syntax

property FIPSMode: Boolean read get_FIPSMode write set_FIPSMode;

Default Value

false

Remarks

This property is reserved for future use.

InputBytes Property (KMIPClient Component)

Use this property to pass the input to component in byte array form.

Syntax

property InputBytes: TBytes read get_InputBytes write set_InputBytes;

Remarks

Assign a byte array containing the data to be processed to this property.

This property is not available at design time.

InputFile Property (KMIPClient Component)

A path to the file containing the data to be passed as input to a cryptographic operation.

Syntax

property InputFile: String read get_InputFile write set_InputFile;

Default Value

''

Remarks

Provide the full path to the file containing data to be signed, verified, encrypted or decrypted.

This property is one of the three ways that you can provide the input data to KMIPClient, with InputBytes and InputStream being the other two.

Key Property (KMIPClient Component)

The key to perform the operations on.

Syntax

property Key: TsbxCryptoKey read get_Key write set_Key;

Remarks

Use this property to provide the key object on which a subsequent operation - such as AddKey - should be performed.

This property is not available at design time.

Please refer to the CryptoKey type for a complete list of fields.

KnownCertificates Property (KMIPClient Component)

Additional certificates for chain validation.

Syntax

property KnownCertificates: TsbxCertificateList read get_KnownCertificates write set_KnownCertificates;

Remarks

Use this property to supply a list of additional certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when intermediary CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of the certificates to be added to this collection is roughly equivalent to that of the Intermediate Certification Authorities system store in Windows.

Do not add trust anchors or root certificates to this collection: add them to TrustedCertificates instead.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

KnownCRLs Property (KMIPClient Component)

Additional CRLs for chain validation.

Syntax

property KnownCRLs: TsbxCRLList read get_KnownCRLs write set_KnownCRLs;

Remarks

Use this property to supply additional CRLs that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated CRLs are stored separately from the signed message or document.

This property is not available at design time.

Please refer to the CRL type for a complete list of fields.

KnownOCSPs Property (KMIPClient Component)

Additional OCSP responses for chain validation.

Syntax

property KnownOCSPs: TsbxOCSPResponseList read get_KnownOCSPs write set_KnownOCSPs;

Remarks

Use this property to supply additional OCSP responses that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated OCSP responses are stored separately from the signed message or document.

This property is not available at design time.

Please refer to the OCSPResponse type for a complete list of fields.

Objects Property (KMIPClient Component)

A list of objects returned by List .

Syntax

property Objects: TsbxKMIPObjectList read get_Objects;

Remarks

This property provides access to the list of objects returned by List.

All, some, or just the ObjectType property of each object will be populated, depending on the value of the Filter parameter that was passed to the List call.

This property is read-only and not available at design time.

Please refer to the KMIPObject type for a complete list of fields.

OutputBytes Property (KMIPClient Component)

Use this property to read the output the component object has produced.

Syntax

property OutputBytes: TBytes read get_OutputBytes;

Remarks

Read the contents of this property after the operation has completed to read the produced output. This property will only be set if the OutputFile and OutputStream properties had not been assigned.

This property is read-only and not available at design time.

OutputFile Property (KMIPClient Component)

Specifies the file where the signed, encrypted, or decrypted data should be saved.

Syntax

property OutputFile: String read get_OutputFile write set_OutputFile;

Default Value

''

Remarks

Provide a full path to the file where the signed, encrypted, or decrypted data should be saved.

This property is one of the three ways that you can receive the output data from KMIPClient, with OutputBytes and OutputStream being the other two.

Password Property (KMIPClient Component)

Specifies a password to authenticate to the KMIP server.

Syntax

property Password: String read get_Password write set_Password;

Default Value

''

Remarks

Use this property to provide a password for authentication on the KMIP server.

The value assigned to this property is used for built-in user authentication provided by KMIP. If the KMIP server you are connecting to expects you to use HTTP basic or digest authentication, provide the credentials via the BaseURL property.

Proxy Property (KMIPClient Component)

The proxy server settings.

Syntax

property Proxy: TsbxProxySettings read get_Proxy;

Remarks

Use this property to tune up the proxy server settings.

This property is read-only.

Please refer to the ProxySettings type for a complete list of fields.

SignatureValidationResult Property (KMIPClient Component)

The signature validation result.

Syntax

property SignatureValidationResult: TsbxSignatureValidities read get_SignatureValidationResult;

TsbxSignatureValidities = (
  svtValid,
  svtUnknown,
  svtCorrupted,
  svtSignerNotFound,
  svtFailure,
  svtReferenceCorrupted
);

Default Value

svtValid

Remarks

Use this property to check the result of the most recent signature validation.

This property is read-only and not available at design time.

SocketSettings Property (KMIPClient Component)

Manages network connection settings.

Syntax

property SocketSettings: TsbxSocketSettings read get_SocketSettings;

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

Please refer to the SocketSettings type for a complete list of fields.

TLSClientChain Property (KMIPClient Component)

The TLS client certificate chain.

Syntax

property TLSClientChain: TsbxCertificateList read get_TLSClientChain write set_TLSClientChain;

Remarks

Assign a certificate chain to this property to enable TLS client authentication in the component. Note that the client's end-entity certificate should have a private key associated with it.

Use the CertificateStorage or CertificateManager components to import the certificate from a file, system store, or PKCS11 device.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

TLSServerChain Property (KMIPClient Component)

The TLS server's certificate chain.

Syntax

property TLSServerChain: TsbxCertificateList read get_TLSServerChain;

Remarks

Use this property to access the certificate chain sent by the TLS server. This property is ready to read when the TLSCertValidate event is fired by the client component.

This property is read-only and not available at design time.

Please refer to the Certificate type for a complete list of fields.

TLSSettings Property (KMIPClient Component)

Manages TLS layer settings.

Syntax

property TLSSettings: TsbxTLSSettings read get_TLSSettings;

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

Please refer to the TLSSettings type for a complete list of fields.

TrustedCertificates Property (KMIPClient Component)

A list of trusted certificates for chain validation.

Syntax

property TrustedCertificates: TsbxCertificateList read get_TrustedCertificates write set_TrustedCertificates;

Remarks

Use this property to supply a list of trusted certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when root CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of this certificate collection is largely the same as that of the Windows Trusted Root Certification Authorities system store.

Use this property with extreme care as it directly affects chain verifiability; a wrong certificate added to the trusted list may result in bad chains being accepted, and forfeited signatures being recognized as genuine. Only add certificates that originate from the parties that you know and trust.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

Username Property (KMIPClient Component)

The username to authenticate to the KMIP server.

Syntax

property Username: String read get_Username write set_Username;

Default Value

''

Remarks

Use this property to provide a username for authentication on the KMIP server.

The value assigned to this property is used for built-in user authentication provided by KMIP. If the KMIP server you are connecting to expects you to use HTTP basic or digest authentication, provide the credentials via the BaseURL property.

Activate Method (KMIPClient Component)

Activates the specified server object.

Syntax

procedure Activate(ObjectId: String);

Remarks

Use this method to activate the object using its ObjectId. Activating the object makes it available for cryptographic operations.

This method is complementary to Deactivate that can be used to disable server-side objects.

Add Method (KMIPClient Component)

Imports a certificate to the KMIP server.

Syntax

function Add(AddPrivateKey: Boolean; Group: String; Activate: Boolean): String;

Remarks

Call this method to import a certificate to the KMIP server. Provide the certificate via Certificate property.

Use the Group parameter to supply a unique identifier for objects associated with this certificate. A typical KMIP server would store two or three objects per certificate - the certificate, its public key, and, if provided, its private key. The shared group identifier will make it easy to establish correspondence between the objects.

Set the AddPrivateKey parameter to true to import the private key (and create a corresponding KMIP object) together with the certificate. Use the Activate parameter to instruct the server to activate the new certificate-related objects immediately.

The method returns the unique identifier of the created certificate object. Check the AuxResult property to read the ID of the associated key object.

AddKey Method (KMIPClient Component)

Imports a key or keypair to the KMIP server.

Syntax

function AddKey(Group: String; Activate: Boolean): String;

Remarks

Use this method to import a key or an asymmetric keypair to the KMIP server. Provide the key via the Key property.

Use the Group parameter to supply a unique identifier for objects associated with this key. Import of an asymmetric keypair may result in two objects being created on the server - the public key and the private key. The shared group identifier will make it easy to establish correspondence between the objects.

Use the Activate parameter to instruct the server to activate the new key objects immediately.

The method returns the unique identifier of the created key object. Check the AuxResult property to read the ID of the second object key component object, if expected.

Config Method (KMIPClient Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

CustomRequest Method (KMIPClient Component)

Performs a custom request to the server.

Syntax

function CustomRequest(Data: TBytes): TBytes;

Remarks

Use this method to send a custom request to the KMIP server. Pass the serialized KMIP request data to the Data parameter. Any response returned back by the server is passed back to the application via the result of this method.

This method can be handy if you need to make a request of the kind that KMIPClient does not support at the moment.

Deactivate Method (KMIPClient Component)

Deactivates the specified server object.

Syntax

procedure Deactivate(ObjectId: String);

Remarks

Use this method to deactivate the object using its ObjectId. Deactivated objects remain on the server but cannot be used for cryptographic operations. Use Remove method to delete objects from the server permanently.

This method is complementary to Activate that lets you enable ('activate') server objects.

Decrypt Method (KMIPClient Component)

Decrypts the provided data using a key stored on the KMIP server.

Syntax

procedure Decrypt(ObjectId: String; Algorithm: String; IV: TBytes; BlockMode: String; PaddingMethod: String; TagLength: Integer);

Remarks

Use this method to decrypt data using the key with the specified ObjectId.

Provide the encrypted data via one of the Input* properties (InputFile, InputStream, or InputBytes). The decrypted data will be saved to one of the output properties.

Use the Algorithm, IV, BlockMode, PaddingMethod, and TagLength parameters to provide adjustments to the decryption algorithm. Not every call will require all of the adjustments. Asymmetric decryption calls (such as RSA) do not typically require parameters.

DoAction Method (KMIPClient Component)

Performs an additional action.

Syntax

function DoAction(ActionID: String; ActionParams: String): String;

Remarks

DoAction is a generic method available in every component. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

Common ActionIDs:

Encrypt Method (KMIPClient Component)

Encrypts the provided data using a key stored on the KMIP server.

Syntax

procedure Encrypt(ObjectId: String; Algorithm: String; IV: TBytes; BlockMode: String; PaddingMethod: String; TagLength: Integer);

Remarks

Use this method to encrypt data using the key with the specified ObjectId. Provide the data to be encrypted via InputFile or InputStream. The encrypted data will be saved to OutputFile (or OutputStream).

Use optional Algorithm, IV, BlockMode, Padding, and TagLength parameters to adjust encryption flow. The values to be passed as these parameters depend on the encryption algorithm being used. Public key algorithms typically do not require these parameters.

Generate Method (KMIPClient Component)

Generates a new certificate on the KMIP server.

Syntax

function Generate(PublicKeyId: String; Activate: Boolean): String;

Remarks

Use this method to generate a new certificate on the server. Set up the needed parameters of the certificate in the Certificate property. This property may contain a prepared certificate request.

An optional PublicKeyId parameter specifies the ID of the server-side public key object to base the certificate on.

The method returns a unique ID assigned to the new certificate object. Note that the certificate itself is not populated in the Certificate property: use Read to request it from the server.

GenerateKey Method (KMIPClient Component)

Generates a symmetric key or an asymmetric key pair on the KMIP server.

Syntax

function GenerateKey(KeyAlgorithm: String; Scheme: String; SchemeParams: String; KeyBits: Integer; Group: String; Activate: Boolean): String;

Remarks

Use KeyAlgorithm and KeyBits to indicate the desired algorithm and key length. Provide an group name of the new key via the Group parameter.

The method returns the ID assigned by the server to the new key object. This may differ from the one you supplied.

Note that the key itself is not populated in the Key property: use ReadKey to request it from the server.

List Method (KMIPClient Component)

Retrieves the list of objects of selected types from the server.

Syntax

procedure List(ObjectTypes: Integer; Filter: String; OffsetItems: Integer; MaximumItems: Integer; FreshOnly: Boolean);

Remarks

ObjectTypes is expected to contain a bit mask according to which objects of one or more types can be selected. The ObjectTypes of 0 implies that there is no mask, and all objects should be returned. Possible values:

Use OffsetItems and MaximumItems to narrow down your search. Use Filter to specify the object properties that you would like to be requested: an empty value or an asterisk tells the client to request all the properties of the listed objects, whereas the objectid filter only results in the object IDs being returned.

Read Method (KMIPClient Component)

Downloads a certificate from the KMIP server.

Syntax

procedure Read(ObjectId: String);

Remarks

Use this method to download a certificate object from the server. Specify the ID of the certificate object via the ObjectId parameter.

Upon completion, the certificate is populated in the Certificate property.

ReadAttribute Method (KMIPClient Component)

Requests an attribute from an object.

Syntax

function ReadAttribute(ObjectId: String; Name: String): String;

Remarks

Use this method to request an attribute defined by the Name parameter for a server-side object indicated by its ObjectId.

The list of attributes supported by KMIP is available here: KMIP v1.3, paragraph 3

ReadKey Method (KMIPClient Component)

Downloads a key object from the KMIP server.

Syntax

procedure ReadKey(ObjectId: String);

Remarks

Use this method to retrieve a key object from the server. Public, private, and secret key IDs can be passed to this method, but only non-sensitive parameters of the private and secret keys will be returned.

The key data is populated in the Key property.

ReadObject Method (KMIPClient Component)

Requests object information from the KMIP server.

Syntax

procedure ReadObject(ObjectId: String);

Remarks

Use this method to request information about a server-side object by its unique ObjectId.

If ObjectId represents a valid certificate or key, the details of the object are populated in Certificate or Key object respectively.

Remove Method (KMIPClient Component)

Removes the specified object from the server.

Syntax

procedure Remove(ObjectId: String);

Remarks

Use this method to delete the object specified by its ObjectId from the KMIP server permanently.

If you would like to disable the object but keep it on the server permanently, use Deactivate method instead.

Reset Method (KMIPClient Component)

Resets the component settings.

Syntax

procedure Reset();

Remarks

Reset is a generic method available in every component.

SetAttribute Method (KMIPClient Component)

Sets an attribute of an existing server-side object.

Syntax

procedure SetAttribute(ObjectId: String; Name: String; Value: String; Delete: Boolean);

Remarks

Use this method to set an attribute of a server-side object.

The list of attributes supported by KMIP is available here: KMIP v1.3, paragraph 3

Set Delete parameter to true to delete the attribute instead of setting it.

SetRequestBytes Method (KMIPClient Component)

Replaces the data that has been prepared for sending out.

Syntax

procedure SetRequestBytes(Value: TBytes);

Remarks

Call this method from your Request event handler to alter the request data being sent to the server. This method method may be handy if you need to adjust the request data that the client has prepared manually before sending it out.

SetResponseBytes Method (KMIPClient Component)

Alters the data received from the server in a response.

Syntax

procedure SetResponseBytes(Value: TBytes);

Remarks

Call this method from your Response event handler to alter the data received from the server before passing it for processing. This method may be handy if you would like to adjust data received from the server - for example, to fix an error in the server's response.

Sign Method (KMIPClient Component)

Signs the data using a key on the KMIP server.

Syntax

procedure Sign(ObjectId: String; Algorithm: String; PaddingMethod: String; HashAlgorithm: String; InputIsHash: Boolean);

Remarks

Use this method to sign the data using the key with the specified ObjectId. Pass the data to be signed via InputFile (or InputStream) property. The resulting signed data will be written to OutputFile (or OutputStream).

The Algorithm and HashAlgorithm parameters should specify the algorithms to be used for the cryptographic signing. Set InputIsHash to true to indicate that you are passing the hash of the data instead of the actual data.

If any of Algorithm or HashAlgorithm are omitted, the server will use the default algorithm associated with the key. Note that this is not always possible, so make sure your requests carry as much details as possible.

The following key algorithms are supported: RSA, EC, ECDSA, ECDH, EDDSA, DSA, ELGAMAL, DH, SRP.

The following hash algorithms are supported: SHA1, SHA256, SHA384, SHA512, SHA224, WHIRLPOOL, POLY1305, SHA3_224, SHA3_256, SHA3_384, SHA3_512. Note that servers may not support all of these algorithms.

Verify Method (KMIPClient Component)

Verifies digitally signed data.

Syntax

procedure Verify(ObjectId: String; Algorithm: String; PaddingMethod: String; HashAlgorithm: String; InputIsHash: Boolean);

Remarks

Use this method to verify the integrity of the signature using a server-side key.

Please provide the signature via InputFile (or InputStream / InputBytes) property. For detached signatures, please also provide the data that was signed via DataFile (or DataStream / DataBytes) property.

Provide additional parameters of the operation:

• Algorithm: the signature algorithm (e.g. sha256WithRSAEncryption).
• PaddingMethod: the padding method used (e.g. PSS).
• HashAlgorithm: the hash algorithm to use for signature verification (e.g. SHA256).
• InputIsHash: specifies whether the data provided via DataFile or similar property contains the data or its message digest.

Error Event (KMIPClient Component)

Provides information about errors during KMIP operations.

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent read FOnError write FOnError;

Remarks

This event is fired in case of exceptional conditions occured during KMIP operations.

ErrorCode contains an error code and Description contains a textual description of the error.

ExternalSign Event (KMIPClient Component)

Handles remote or external signing initiated by the SignExternal method or other source.

Syntax

type TExternalSignEvent = procedure (
  Sender: TObject;
  const OperationId: String;
  const HashAlgorithm: String;
  const Pars: String;
  const Data: String;
  var SignedData: String
) of Object;

property OnExternalSign: TExternalSignEvent read FOnExternalSign write FOnExternalSign;

Remarks

Assign a handler to this event if you need to delegate a low-level signing operation to an external, remote, or custom signing engine. Depending on the settings, the handler will receive a hashed or unhashed value to be signed.

The event handler must pass the value of Data to the signer, obtain the signature, and pass it back to the component via the SignedData parameter.

OperationId provides a comment about the operation and its origin. It depends on the exact component being used, and may be empty. HashAlgorithm specifies the hash algorithm being used for the operation, and Pars contains algorithm-dependent parameters.

The component uses base16 (hex) encoding for the Data, SignedData, and Pars parameters. If your signing engine uses a different input and output encoding, you may need to decode and/or encode the data before and/or after the signing.

A sample MD5 hash encoded in base16: a0dee2a0382afbb09120ffa7ccd8a152 - lower case base16 A0DEE2A0382AFBB09120FFA7CCD8A152 - upper case base16

A sample event handler that uses the .NET RSACryptoServiceProvider class may look like the following: signer.OnExternalSign += (s, e) => { var cert = new X509Certificate2("cert.pfx", "", X509KeyStorageFlags.Exportable); var key = (RSACryptoServiceProvider)cert.PrivateKey; var dataToSign = e.Data.FromBase16String(); var signedData = key.SignHash(dataToSign, "2.16.840.1.101.3.4.2.1"); e.SignedData = signedData.ToBase16String(); };

Notification Event (KMIPClient Component)

This event notifies the application about an underlying control flow event.

Syntax

type TNotificationEvent = procedure (
  Sender: TObject;
  const EventID: String;
  const EventParam: String
) of Object;

property OnNotification: TNotificationEvent read FOnNotification write FOnNotification;

Remarks

The component fires this event to let the application know about some event, occurrence, or milestone in the component. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, the exact action it is performing, or the document being processed, one or both may be omitted.

This component can fire this event with the following EventID values:

Request Event (KMIPClient Component)

KMIPClient fires this event to notify the user about the request being sent to the KMIP server.

Syntax

type TRequestEvent = procedure (
  Sender: TObject;
  const RequestData: TBytes
) of Object;

property OnRequest: TRequestEvent read FOnRequest write FOnRequest;

Remarks

Subscribe to this event to be notified about individual requests sent by the KMIP client to the server.

The RequestData parameter contains the encoded KMIP request. You can alter what is being sent by providing custom request bytes via the SetRequestBytes method.

Response Event (KMIPClient Component)

KMIPClient uses this event to notify the user about the response being received.

Syntax

type TResponseEvent = procedure (
  Sender: TObject;
  const ResponseData: TBytes
) of Object;

property OnResponse: TResponseEvent read FOnResponse write FOnResponse;

Remarks

Subscribe to this event to be notified about KMIP protocol responses that the KMIP client receives from the server.

The ResponseData parameter contains the encoded body of the response. Use SetResponseBytes to alter the response data received before it is processed by the client.

TLSCertNeeded Event (KMIPClient Component)

Fires when a remote TLS party requests a client certificate.

Syntax

type TTLSCertNeededEvent = procedure (
  Sender: TObject;
  const Host: String;
  const CANames: String
) of Object;

property OnTLSCertNeeded: TTLSCertNeededEvent read FOnTLSCertNeeded write FOnTLSCertNeeded;

Remarks

This event fires to notify the implementation that a remote TLS server has requested a client certificate. The Host parameter identifies the host that makes a request, and the CANames parameter (optional, according to the TLS spec) advises on the accepted issuing CAs.

Use the TLSClientChain property in response to this event to provide the requested certificate. Please make sure the client certificate includes the associated private key. Note that you may set the certificates before the connection without waiting for this event to fire.

This event is preceded by the TLSHandshake event for the given host and, if the certificate was accepted, succeeded by the TLSEstablished event.

TLSCertValidate Event (KMIPClient Component)

This event is fired upon receipt of the TLS server's certificate, allowing the user to control its acceptance.

Syntax

type TTLSCertValidateEvent = procedure (
  Sender: TObject;
  const ServerHost: String;
  const ServerIP: String;
  var Accept: Boolean
) of Object;

property OnTLSCertValidate: TTLSCertValidateEvent read FOnTLSCertValidate write FOnTLSCertValidate;

Remarks

This event is fired during a TLS handshake. Use the TLSServerChain property to access the certificate chain. In general, components may contact a number of TLS endpoints during their work, depending on their configuration.

Accept is assigned in accordance with the outcome of the internal validation check performed by the component, and can be adjusted if needed.

TLSEstablished Event (KMIPClient Component)

Fires when a TLS handshake with Host successfully completes.

Syntax

type TTLSEstablishedEvent = procedure (
  Sender: TObject;
  const Host: String;
  const Version: String;
  const Ciphersuite: String;
  const ConnectionId: TBytes;
  var Abort: Boolean
) of Object;

property OnTLSEstablished: TTLSEstablishedEvent read FOnTLSEstablished write FOnTLSEstablished;

Remarks

The component uses this event to notify the application about a successful completion of a TLS handshake.

The Version, Ciphersuite, and ConnectionId parameters indicate the security parameters of the new connection. Use the Abort parameter if you need to terminate the connection at this stage.

TLSHandshake Event (KMIPClient Component)

Fires when a new TLS handshake is initiated, before the handshake commences.

Syntax

type TTLSHandshakeEvent = procedure (
  Sender: TObject;
  const Host: String;
  var Abort: Boolean
) of Object;

property OnTLSHandshake: TTLSHandshakeEvent read FOnTLSHandshake write FOnTLSHandshake;

Remarks

The component uses this event to notify the application about the start of a new TLS handshake to Host. If the handshake is successful, this event will be followed by the TLSEstablished event. If the server chooses to request a client certificate, the TLSCertNeeded event will also be fired.

TLSPSK Event (KMIPClient Component)

Notifies the application about the PSK key exchange.

Syntax

type TTLSPSKEvent = procedure (
  Sender: TObject;
  const Host: String;
  const Hint: String
) of Object;

property OnTLSPSK: TTLSPSKEvent read FOnTLSPSK write FOnTLSPSK;

Remarks

The component fires this event to notify the application about the beginning of TLS-PSK key exchange with Host. The Hint parameter may be used by the server to identify the key or service to use. Use the PreSharedKey field of TLSSettings to provide the pre-shared key to the component.

TLSShutdown Event (KMIPClient Component)

Reports the graceful closure of a TLS connection.

Syntax

type TTLSShutdownEvent = procedure (
  Sender: TObject;
  const Host: String
) of Object;

property OnTLSShutdown: TTLSShutdownEvent read FOnTLSShutdown write FOnTLSShutdown;

Remarks

This event notifies the application about the closure of an earlier established TLS connection. Note that only graceful connection closures are reported.

Certificate Type

Encapsulates an individual X.509 certificate.

Remarks

This type keeps and provides access to X.509 certificate details.

Fields

Constructors

>

constructor Create();

CRL Type

Represents a Certificate Revocation List.

Remarks

CRLs store information about revoked certificates, i.e., certificates that have been identified as invalid by their issuing certificate authority (CA) for any number of reasons.

Each CRL object lists certificates from a single CA and identifies them by their serial numbers. A CA may or may not publish a CRL, may publish several CRLs, or may publish the same CRL in multiple locations.

Unlike OCSP responses, CRLs only list certificates that have been revoked. They do not list certificates that are still valid.

Fields

Constructors

>

constructor Create();

CryptoKey Type

This container represents a cryptographic key.

Remarks

This type is a universal placeholder for cryptographic keys.

Fields

Constructors

>

constructor Create();

ExternalCrypto Type

Specifies the parameters of external cryptographic calls.

Remarks

External cryptocalls are used in a Distributed Cryptography (DC) subsystem, which allows the delegation of security operations to the remote agent. For instance, it can be used to compute the signature value on the server, while retaining the client's private key locally.

Fields

Constructors

>

constructor Create();

KMIPObject Type

A container representing a KMIP object.

Remarks

KMIPObject represents an object before it is committed to the KMIP server or after it has been read from there. Certificates, certificate requests, keys, and data objects are examples of KMIP objects.

Fields

Constructors

>

constructor Create();

OCSPResponse Type

Represents a single OCSP response originating from an OCSP responder.

Remarks

OCSP is a protocol that allows verification of certificate status in real-time, and is an alternative to Certificate Revocation Lists (CRLs).

An OCSP response is a snapshot of the certificate status at a given time.

Fields

Constructors

>

constructor Create();

ProxySettings Type

A container for proxy server settings.

Remarks

This type exposes a collection of properties for tuning up the proxy server configuration.

Fields

Constructors

>

constructor Create();

SocketSettings Type

A container for the socket settings.

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

>

constructor Create();

TLSConnectionInfo Type

Contains information about a network connection.

Remarks

Use this property to check various details of the network connection. These include the total amounts of data transferred, the availability of TLS, and its parameters.

Fields

Constructors

>

constructor Create();

TLSSettings Type

A container for TLS connection settings.

Remarks

The TLS (Transport Layer Security) protocol provides security for information exchanged over insecure connections such as TCP/IP.

Fields

Constructors

>

constructor Create();

Config Settings (KMIPClient Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

KMIPClient Config Settings

Base Config Settings

Trappable Errors (KMIPClient Component)

KMIPClient Errors