KMIPClient Class

Properties   Methods   Events   Config Settings   Errors  

The KMIPClient class provides client-side functionality for KMIP.

Syntax

secureblackbox.Kmipclient

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 class with short descriptions. Click on the links for further details.

Method List

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

Event List

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

Config Settings

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

DataFile Property (KMIPClient Class)

A path to the file containing the unsigned data.

Syntax

public String getDataFile();


public void setDataFile(String dataFile);

Default Value

""

Remarks

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

DataStream Property (KMIPClient Class)

A stream containing the unsigned data.

Syntax

public java.io.InputStream getDataStream();


public void setDataStream(java.io.InputStream dataStream);

Default Value

null

Remarks

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

This property is not available at design time.

EncoderType Property (KMIPClient Class)

Specifies the KMIP encoder type.

Syntax

public int getEncoderType();


public void setEncoderType(int encoderType);


Enumerated values:
  public final static int etTTLV = 0;
  public final static int etXML = 1;
  public final static int etJSON = 2;

Default Value

0

Remarks

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

ExternalCrypto Property (KMIPClient Class)

Provides access to external signing and DC parameters.

Syntax

public ExternalCrypto getExternalCrypto();

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.

FIPSMode Property (KMIPClient Class)

Reserved.

Syntax

public boolean isFIPSMode();


public void setFIPSMode(boolean FIPSMode);

Default Value

False

Remarks

This property is reserved for future use.

Host Property (KMIPClient Class)

Specifies the host name of the KMIP server.

Syntax

public String getHost();


public void setHost(String host);

Default Value

""

Remarks

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

InputFile Property (KMIPClient Class)

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

Syntax

public String getInputFile();


public void setInputFile(String inputFile);

Default Value

""

Remarks

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

InputStream Property (KMIPClient Class)

A stream containing data to be signed, verified, encrypted or decrypted.

Syntax

public java.io.InputStream getInputStream();


public void setInputStream(java.io.InputStream inputStream);

Default Value

null

Remarks

Use this property to provide the stream containing the data to be processed.

This property is not available at design time.

Objects Property (KMIPClient Class)

A list of objects returned by GetList .

Syntax

public KMIPObjectList getObjects();

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 Class)

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

Syntax

public String getOutputFile();


public void setOutputFile(String outputFile);

Default Value

""

Remarks

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

OutputStream Property (KMIPClient Class)

The stream where the signed, encrypted, or decrypted document should be saved.

Syntax

public java.io.OutputStream getOutputStream();


public void setOutputStream(java.io.OutputStream outputStream);

Default Value

null

Remarks

Use this property to provide the stream to write the signed, encrypted, or decrypted data to.

This property is not available at design time.

Password Property (KMIPClient Class)

Specifies a password to authenticate to the KMIP server.

Syntax

public String getPassword();


public void setPassword(String password);

Default Value

""

Remarks

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

PinnedCert Property (KMIPClient Class)

The certificate to perform operations on.

Syntax

public Certificate getPinnedCert();


public void setPinnedCert(Certificate 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 Class)

The certificate request to perform operations on.

Syntax

public CertificateRequest getPinnedCertRequest();


public void setPinnedCertRequest(CertificateRequest 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 Class)

Specifies the port on the KMIP server to connect to.

Syntax

public int getPort();


public void setPort(int port);

Default Value

0

Remarks

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

Proxy Property (KMIPClient Class)

The proxy server settings.

Syntax

public ProxySettings getProxy();

Remarks

Use this property to tune up the proxy server settings.

This property is read-only.

SignatureValidationResult Property (KMIPClient Class)

The signature validation result.

Syntax

public int getSignatureValidationResult();



Enumerated values:
  public final static int svtValid = 0;
  public final static int svtUnknown = 1;
  public final static int svtCorrupted = 2;
  public final static int svtSignerNotFound = 3;
  public final static int svtFailure = 4;

Default Value

0

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 Class)

Manages network connection settings.

Syntax

public SocketSettings getSocketSettings();

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

TLSClientChain Property (KMIPClient Class)

The TLS client certificate chain.

Syntax

public CertificateList getTLSClientChain();


public void setTLSClientChain(CertificateList TLSClientChain);

Remarks

Assign a certificate chain to this property to enable TLS client authentication in the class. 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.

TLSServerChain Property (KMIPClient Class)

The TLS server's certificate chain.

Syntax

public CertificateList getTLSServerChain();

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.

TLSSettings Property (KMIPClient Class)

Manages TLS layer settings.

Syntax

public TLSSettings getTLSSettings();

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

Username Property (KMIPClient Class)

The username to authenticate to the KMIP server.

Syntax

public String getUsername();


public void setUsername(String username);

Default Value

""

Remarks

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

AddCertificate Method (Kmipclient Class)

Imports a certificate to the KMIP server.

Syntax

public String addCertificate(String certPassword, boolean addPrivateKey, String id);

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 Class)

Imports a key to the KMIP server.

Syntax

public String addKey(String id);

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 Class)

Imports a certificate to the KMIP server.

Syntax

public String addPinned(boolean addPrivateKey, String id);

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 Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, 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 Class)

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

Syntax

public void decrypt(String uniqueIdentifier);

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 Class)

Performs an additional action.

Syntax

public String doAction(String actionID, String actionParams);

Remarks

DoAction is a generic method available in every class. 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;....

Encrypt Method (Kmipclient Class)

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

Syntax

public void encrypt(String uniqueIdentifier);

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 Class)

Generates a new certificate on the KMIP server.

Syntax

public String generateCert(String publicKeyUniqueIdentifier, String keyAlgorithm, String hashAlgorithm, int keyLength, String subjectRDN, String id);

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 Class)

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

Syntax

public String generateCertFromPinned(String publicKeyUniqueIdentifier, String id);

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 Class)

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

Syntax

public String generateCertFromRequest(String id);

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 Class)

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

Syntax

public String generateKey(String keyAlgorithm, int keyLength, String id);

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 Class)

Retrieves the list of objects of a given type.

Syntax

public void getList(int objectTypes);

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 Class)

Removes the specified object from the server.

Syntax

public void remove(String uniqueIdentifier);

Remarks

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

Sign Method (Kmipclient Class)

Signs the data using a key on the KMIP server.

Syntax

public void sign(String uniqueIdentifier);

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 Class)

Verifies digitally signed data.

Syntax

public void verify(String uniqueIdentifier);

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 Class)

Provides information about errors during KMIP operations.

Syntax

public class DefaultKmipclientEventListener implements KmipclientEventListener {
  ...
  public void error(KmipclientErrorEvent e) {}
  ...
}

public class KmipclientErrorEvent {
  public int errorCode;
  public String description;
}

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 Class)

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

Syntax

public class DefaultKmipclientEventListener implements KmipclientEventListener {
  ...
  public void externalSign(KmipclientExternalSignEvent e) {}
  ...
}

public class KmipclientExternalSignEvent {
  public String operationId;
  public String hashAlgorithm;
  public String pars;
  public String data;
  public String signedData;
}

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 class via the SignedData parameter.

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

The class 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:

 
 Copy
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 Class)

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

Syntax

public class DefaultKmipclientEventListener implements KmipclientEventListener {
  ...
  public void notification(KmipclientNotificationEvent e) {}
  ...
}

public class KmipclientNotificationEvent {
  public String eventID;
  public String eventParam;
}

Remarks

The class fires this event to let the application know about some event, occurrence, or milestone in the class. 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 class, the exact action it is performing, or the document being processed, one or both may be omitted.

TLSCertNeeded Event (Kmipclient Class)

Fires when a remote TLS party requests a client certificate.

Syntax

public class DefaultKmipclientEventListener implements KmipclientEventListener {
  ...
  public void TLSCertNeeded(KmipclientTLSCertNeededEvent e) {}
  ...
}

public class KmipclientTLSCertNeededEvent {
  public String host;
  public String CANames;
}

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 Class)

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

Syntax

public class DefaultKmipclientEventListener implements KmipclientEventListener {
  ...
  public void TLSCertValidate(KmipclientTLSCertValidateEvent e) {}
  ...
}

public class KmipclientTLSCertValidateEvent {
  public String serverHost;
  public String serverIP;
  public boolean accept;
}

Remarks

This event is fired during a TLS handshake. Use the TLSServerChain property to access the certificate chain. In general, classes 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 class, and can be adjusted if needed.

TLSEstablished Event (Kmipclient Class)

Fires when a TLS handshake with Host successfully completes.

Syntax

public class DefaultKmipclientEventListener implements KmipclientEventListener {
  ...
  public void TLSEstablished(KmipclientTLSEstablishedEvent e) {}
  ...
}

public class KmipclientTLSEstablishedEvent {
  public String host;
  public String version;
  public String ciphersuite;
  public byte[] connectionId;
  public boolean abort;
}

Remarks

The class 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 Class)

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

Syntax

public class DefaultKmipclientEventListener implements KmipclientEventListener {
  ...
  public void TLSHandshake(KmipclientTLSHandshakeEvent e) {}
  ...
}

public class KmipclientTLSHandshakeEvent {
  public String host;
  public boolean abort;
}

Remarks

The class 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.

TLSShutdown Event (Kmipclient Class)

Reports the graceful closure of a TLS connection.

Syntax

public class DefaultKmipclientEventListener implements KmipclientEventListener {
  ...
  public void TLSShutdown(KmipclientTLSShutdownEvent e) {}
  ...
}

public class KmipclientTLSShutdownEvent {
  public String host;
}

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

Constructors

public Certificate( bytes,  startIndex,  count,  password);

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

public Certificate( certBytes,  certStartIndex,  certCount,  keyBytes,  keyStartIndex,  keyCount,  password);

Loads the X.509 certificate from a memory buffer. CertBytes is a buffer containing the raw certificate data. CertStartIndex and CertCount specify the number of bytes to be read from the buffer, respectively. KeyBytes is a buffer containing the private key data. KeyStartIndex and KeyCount specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

public Certificate( bytes,  startIndex,  count);

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively.

public Certificate( path,  password);

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data. Password is a password encrypting the certificate.

public Certificate( certPath,  keyPath,  password);

Loads the X.509 certificate from a file. CertPath specifies the full path to the file containing the certificate data. KeyPath specifies the full path to the file containing the private key. Password is a password encrypting the certificate.

public Certificate( path);

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data.

public Certificate( stream);

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data.

public Certificate( stream,  password);

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data. Password is a password encrypting the certificate.

public Certificate( certStream,  keyStream,  password);

Loads the X.509 certificate from a stream. CertStream is a stream containing the certificate data. KeyStream is a stream containing the private key. Password is a password encrypting the certificate.

public Certificate();

Creates a new object with default field values.

CertificateRequest Type

Provides access to details of an individual certificate request (CSR).

Remarks

This type represents a certificate request as defined in PKCS#10.

Fields

Constructors

public CertificateRequest( bytes,  startIndex,  count);

Loads the certificate request from a memory buffer. Bytes is a buffer containing raw certificate request data, StartIndex and Count specify the starting position and number of bytes to be read from the buffer.

public CertificateRequest( path);

Loads the certificate request from a file. Path specifies the full path to the file containing the certificate request data.

public CertificateRequest( stream);

Loads the certificate request from a stream. Stream is a stream containing the certificate request data.

public CertificateRequest();

Creates a new object with default field values.

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

 
 Copy
  signer.ExternalCrypto.KeyID = "MainSigningKey";
  signer.ExternalCrypto.KeySecret = "abcdef0123456789";

Constructors

public ExternalCrypto();

Creates a new ExternalCrypto object with default field values.

KMIPObject Type

A container representing a KMIP object.

Remarks

KMIPObject represents an object stored on the KMIP server. Certificates, certificate requests, and keys are examples of KMIP objects.

Fields

Constructors

public KMIPObject();

Creates a new KMIP object with the default field values.

public KMIPObject( AUniqueIdentifier,  AObjectType,  ADigitalSignatureAlgorithm,  ACryptographicAlgorithm,  ACryptographicLength,  AID);

Creates a new KMIP object with the specified field values. Supported object types: otCertificate 0x01 otSymmetricKey 0x02 otPublicKey 0x04 otPrivateKey 0x08 .

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

public ProxySettings();

Creates a new ProxySettings object.

SocketSettings Type

A container for the socket settings.

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

public SocketSettings();

Creates a new SocketSettings object.

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

public TLSSettings();

Creates a new TLSSettings object.

Config Settings (Kmipclient Class)

KMIPClient Config Settings

Base Config Settings

Trappable Errors (Kmipclient Class)

KMIPClient Errors