KMIPClient Component

Properties   Methods   Events   Config Settings   Errors  

The KMIPClient component provides client-side functionality for KMIP.

Syntax

TsbxKMIPClient

Remarks

The Key Management Interoperability Protocol (KMIP) is an OASIS standard for communication between different key management servers and clients.

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.

DataFile Property (KMIPClient Component)

A path to the file containing the unsigned data.

Syntax

property DataFile: String read get_DataFile write set_DataFile;

Default Value

''

Remarks

When validating detached signatures, use this property to provide the unsigned data.

EncoderType Property (KMIPClient Component)

Specifies the KMIP encoder type.

Syntax

property EncoderType: TsbxKMIPEncoderTypes read get_EncoderType write set_EncoderType;

TsbxKMIPEncoderTypes = (
  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.

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 OnExternalSign event) and asynchronous (based on DC protocol and DCAuth signing component).

This property is read-only.

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.

Host Property (KMIPClient Component)

Specifies the host name of the KMIP server.

Syntax

property Host: String read get_Host write set_Host;

Default Value

''

Remarks

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

InputFile Property (KMIPClient Component)

Path to the file containing data to be signed, verified, encrypted or decrypted.

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.

Objects Property (KMIPClient Component)

A list of objects returned by GetList .

Syntax

property Objects: TsbxKMIPObjectList read get_Objects;

Remarks

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

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.

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.

PinnedCert Property (KMIPClient Component)

The certificate to perform operations on.

Syntax

property PinnedCert: TsbxCertificate read get_PinnedCert write set_PinnedCert;

Remarks

Use this property to provide the certificate object on which a subsequent operation should be performed.

This property is not available at design time.

PinnedCertRequest Property (KMIPClient Component)

The certificate request to perform operations on.

Syntax

property PinnedCertRequest: TsbxCertificateRequest read get_PinnedCertRequest write set_PinnedCertRequest;

Remarks

Use this property to provide the certificate request object on which a subsequent operation should be performed.

This property is not available at design time.

Port Property (KMIPClient Component)

Specifies the port on the KMIP server to connect to.

Syntax

property Port: Integer read get_Port write set_Port;

Default Value

0

Remarks

Provide the port number on which the component should make requests to the KMIP server.

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.

SignatureValidationResult Property (KMIPClient Component)

The signature validation result.

Syntax

property SignatureValidationResult: TsbxSignatureValidities read get_SignatureValidationResult;

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

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.

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.

This property is not available at design time.

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 read-only and not available at design time.

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.

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.

AddCertificate Method (KMIPClient Component)

Imports a certificate to the KMIP server.

Syntax

function AddCertificate(CertPassword: String; AddPrivateKey: Boolean; Id: String): String;

Remarks

Call this method to import a certificate to the KMIP server. Provide the key via InputFile or InputStream property.

Use the Id parameter to supply a unique certificate object identifier. AddPrivateKey instructs the component to import the private key as well. The method returns the actual ID of the new object, which may differ from the supplied one.

AddKey Method (KMIPClient Component)

Imports a key to the KMIP server.

Syntax

function AddKey(Id: String): String;

Remarks

Call this method to import a key to the KMIP server. Provide the key via InputFile or InputStream property.

Use the Id parameter to supply a unique certificate object identifier. The method returns the actual ID of the new object, which may differ from the supplied one.

AddPinned Method (KMIPClient Component)

Imports a certificate to the KMIP server.

Syntax

function AddPinned(AddPrivateKey: Boolean; Id: String): String;

Remarks

Call this method to import a certificate to the KMIP server. Provide the certificate in PinnedCert property.

Use the Id parameter to supply a unique certificate object identifier. AddPrivateKey instructs the component to import the private key as well. The method returns the actual ID of the new object, which may differ from the supplied one.

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.

Decrypt Method (KMIPClient Component)

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

Syntax

procedure Decrypt(UniqueIdentifier: String);

Remarks

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

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 insencitive) 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;....

Encrypt Method (KMIPClient Component)

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

Syntax

procedure Encrypt(UniqueIdentifier: String);

Remarks

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

GenerateCert Method (KMIPClient Component)

Generates a new certificate on the KMIP server.

Syntax

function GenerateCert(PublicKeyUniqueIdentifier: String; KeyAlgorithm: String; HashAlgorithm: String; KeyLength: Integer; SubjectRDN: String; Id: String): String;

Remarks

Use KeyAlgorithm, HashAlgorithm, and KeyLength to specify the desired algorithms and key length. SubjectRDN should identify the new certificate's owner.

Use the Id parameter to suggest a unique identifier for the certificate object. The method returns the actual Id assigned to the new certificate (it may differ from the one you supplied).

GenerateCertFromPinned Method (KMIPClient Component)

Generates a new certificate on the KMIP server from the pinned certificate.

Syntax

function GenerateCertFromPinned(PublicKeyUniqueIdentifier: String; Id: String): String;

Remarks

Use the Id parameter to provide a unique identifier for the new certificate. The method will return the actual Id assigned to the new certificate, which may differ from the one you provided.

GenerateCertFromRequest Method (KMIPClient Component)

Generates a new certificate on the KMIP server from the certificate request.

Syntax

function GenerateCertFromRequest(Id: String): String;

Remarks

Provide the certificate request via PinnedCertRequest property. The returned value contains the Id assigned to the certificate, which may differ from the one you supplied.

GenerateKey Method (KMIPClient Component)

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

Syntax

function GenerateKey(KeyAlgorithm: String; KeyLength: Integer; Id: String): String;

Remarks

Use KeyAlgorithm and KeyLength to indicate the desired algorithm and key length. Provide an identifier (name) of the new key via the Id parameter.

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

GetList Method (KMIPClient Component)

Retrieves the list of objects of a given type.

Syntax

procedure GetList(ObjectTypes: Integer);

Remarks

ObjectTypes is a bit mask according to which objects of one or more types can be selected. Possible values:

If ObjectTypes of 0 is provided, all objects will be requested from the server.

Remove Method (KMIPClient Component)

Removes the specified object from the server.

Syntax

procedure Remove(UniqueIdentifier: String);

Remarks

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

Sign Method (KMIPClient Component)

Signs the data using a key on the KMIP server.

Syntax

procedure Sign(UniqueIdentifier: String);

Remarks

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

Verify Method (KMIPClient Component)

Verifies digitally signed data.

Syntax

procedure Verify(UniqueIdentifier: String);

Remarks

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

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

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 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 contain algorithm-dependent parameters.

The component uses base16 (hex) encoding for 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 a .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 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.

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 (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 TLSServerChain property to access the certificate chain. In general case, 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;
  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 successful completion of a TLS handshake.

The Version, Ciphersuite, and ConnectionId parameters indicate 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 with TLSEstablished event. If the server chooses to request a client certificate, TLSCertNeeded event will also be fired.

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

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

constructor Create();

constructor Create();

constructor Create();

constructor Create();

constructor Create();

constructor Create();

constructor Create();

Config Settings (KMIPClient Component)

KMIPClient Config Settings

Base Config Settings

Trappable Errors (KMIPClient Component)

KMIPClient Errors