KMIPClient Module

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

SecureBlackbox.KMIPClient

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

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.

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.

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

Method List

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

Event List

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

Config Settings

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

AuthTypes Property (KMIPClient Module)

Defines allowed HTTP authentication types.

Syntax

• Swift
• Objective-C

public var authTypes: Int32 {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=authTypes,setter=setAuthTypes:) int authTypes;

- (int)authTypes;
- (void)setAuthTypes :(int)newAuthTypes;

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

Contains the auxiliary result of the last performed operation.

Syntax

• Swift
• Objective-C

public var auxResult: String {
  get {...}
}

@property (nonatomic,readonly,assign,getter=auxResult) NSString* auxResult;

- (NSString*)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 Module)

Specifies the url of the KMIP server.

Syntax

• Swift
• Objective-C

public var baseURL: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=baseURL,setter=setBaseURL:) NSString* baseURL;

- (NSString*)baseURL;
- (void)setBaseURL :(NSString*)newBaseURL;

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

The certificates that must be rejected as trust anchors.

Syntax

• Swift
• Objective-C

public var blockedCertificates: Array<Certificate> {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=blockedCertCount,setter=setBlockedCertCount:) int blockedCertCount;

- (int)blockedCertCount;
- (void)setBlockedCertCount :(int)newBlockedCertCount;

- (NSData*)blockedCertBytes:(int)blockedCertIndex;

- (long long)blockedCertHandle:(int)blockedCertIndex;
- (void)setBlockedCertHandle:(int)blockedCertIndex :(long long)newBlockedCertHandle;

Default Value

""

Remarks

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

Certificate Property (KMIPClient Module)

The certificate or request object to perform operations on.

Syntax

• Swift
• Objective-C

public var certificate: Certificate {
  get {...}
  set {...}
}

@property (nonatomic,readonly,assign,getter=certificateBytes) NSData* certificateBytes;

- (NSData*)certificateBytes;

@property (nonatomic,readwrite,assign,getter=certificateHandle,setter=setCertificateHandle:) long long certificateHandle;

- (long long)certificateHandle;
- (void)setCertificateHandle :(long long)newCertificateHandle;

 

Default Value

""

Remarks

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

ConnectionInfo Property (KMIPClient Module)

Returns the details of the underlying network connection.

Syntax

• Swift
• Objective-C

public var connectionInfo: TLSConnectionInfo {
  get {...}
}

@property (nonatomic,readonly,assign,getter=connInfoAEADCipher) BOOL connInfoAEADCipher;

- (BOOL)connInfoAEADCipher;

@property (nonatomic,readonly,assign,getter=connInfoChainValidationDetails) int connInfoChainValidationDetails;

- (int)connInfoChainValidationDetails;

@property (nonatomic,readonly,assign,getter=connInfoChainValidationResult) int connInfoChainValidationResult;

- (int)connInfoChainValidationResult;

@property (nonatomic,readonly,assign,getter=connInfoCiphersuite) NSString* connInfoCiphersuite;

- (NSString*)connInfoCiphersuite;

@property (nonatomic,readonly,assign,getter=connInfoClientAuthenticated) BOOL connInfoClientAuthenticated;

- (BOOL)connInfoClientAuthenticated;

@property (nonatomic,readonly,assign,getter=connInfoClientAuthRequested) BOOL connInfoClientAuthRequested;

- (BOOL)connInfoClientAuthRequested;

@property (nonatomic,readonly,assign,getter=connInfoConnectionEstablished) BOOL connInfoConnectionEstablished;

- (BOOL)connInfoConnectionEstablished;

@property (nonatomic,readonly,assign,getter=connInfoConnectionID) NSData* connInfoConnectionID;

- (NSData*)connInfoConnectionID;

@property (nonatomic,readonly,assign,getter=connInfoDigestAlgorithm) NSString* connInfoDigestAlgorithm;

- (NSString*)connInfoDigestAlgorithm;

@property (nonatomic,readonly,assign,getter=connInfoEncryptionAlgorithm) NSString* connInfoEncryptionAlgorithm;

- (NSString*)connInfoEncryptionAlgorithm;

@property (nonatomic,readonly,assign,getter=connInfoExportable) BOOL connInfoExportable;

- (BOOL)connInfoExportable;

@property (nonatomic,readonly,assign,getter=connInfoID) long long connInfoID;

- (long long)connInfoID;

@property (nonatomic,readonly,assign,getter=connInfoKeyExchangeAlgorithm) NSString* connInfoKeyExchangeAlgorithm;

- (NSString*)connInfoKeyExchangeAlgorithm;

@property (nonatomic,readonly,assign,getter=connInfoKeyExchangeKeyBits) int connInfoKeyExchangeKeyBits;

- (int)connInfoKeyExchangeKeyBits;

@property (nonatomic,readonly,assign,getter=connInfoNamedECCurve) NSString* connInfoNamedECCurve;

- (NSString*)connInfoNamedECCurve;

@property (nonatomic,readonly,assign,getter=connInfoPFSCipher) BOOL connInfoPFSCipher;

- (BOOL)connInfoPFSCipher;

@property (nonatomic,readonly,assign,getter=connInfoPreSharedIdentity) NSString* connInfoPreSharedIdentity;

- (NSString*)connInfoPreSharedIdentity;

@property (nonatomic,readonly,assign,getter=connInfoPreSharedIdentityHint) NSString* connInfoPreSharedIdentityHint;

- (NSString*)connInfoPreSharedIdentityHint;

@property (nonatomic,readonly,assign,getter=connInfoPublicKeyBits) int connInfoPublicKeyBits;

- (int)connInfoPublicKeyBits;

@property (nonatomic,readonly,assign,getter=connInfoRemoteAddress) NSString* connInfoRemoteAddress;

- (NSString*)connInfoRemoteAddress;

@property (nonatomic,readonly,assign,getter=connInfoRemotePort) int connInfoRemotePort;

- (int)connInfoRemotePort;

@property (nonatomic,readonly,assign,getter=connInfoResumedSession) BOOL connInfoResumedSession;

- (BOOL)connInfoResumedSession;

@property (nonatomic,readonly,assign,getter=connInfoSecureConnection) BOOL connInfoSecureConnection;

- (BOOL)connInfoSecureConnection;

@property (nonatomic,readonly,assign,getter=connInfoServerAuthenticated) BOOL connInfoServerAuthenticated;

- (BOOL)connInfoServerAuthenticated;

@property (nonatomic,readonly,assign,getter=connInfoSignatureAlgorithm) NSString* connInfoSignatureAlgorithm;

- (NSString*)connInfoSignatureAlgorithm;

@property (nonatomic,readonly,assign,getter=connInfoSymmetricBlockSize) int connInfoSymmetricBlockSize;

- (int)connInfoSymmetricBlockSize;

@property (nonatomic,readonly,assign,getter=connInfoSymmetricKeyBits) int connInfoSymmetricKeyBits;

- (int)connInfoSymmetricKeyBits;

@property (nonatomic,readonly,assign,getter=connInfoTotalBytesReceived) long long connInfoTotalBytesReceived;

- (long long)connInfoTotalBytesReceived;

@property (nonatomic,readonly,assign,getter=connInfoTotalBytesSent) long long connInfoTotalBytesSent;

- (long long)connInfoTotalBytesSent;

@property (nonatomic,readonly,assign,getter=connInfoValidationLog) NSString* connInfoValidationLog;

- (NSString*)connInfoValidationLog;

@property (nonatomic,readonly,assign,getter=connInfoVersion) NSString* connInfoVersion;

- (NSString*)connInfoVersion;

 

Default Value

""

Remarks

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

DataBytes Property (KMIPClient Module)

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

Syntax

• Swift
• Objective-C

public var dataBytes: Data {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=dataBytes,setter=setDataBytes:) NSData* dataBytes;

- (NSData*)dataBytes;
- (void)setDataBytes :(NSData*)newDataBytes;

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.

DataFile Property (KMIPClient Module)

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

Syntax

• Swift
• Objective-C

public var dataFile: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=dataFile,setter=setDataFile:) NSString* dataFile;

- (NSString*)dataFile;
- (void)setDataFile :(NSString*)newDataFile;

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

Specifies the KMIP encoding type.

Syntax

• Swift
• Objective-C

public var encoding: KMIPClientEncodings {
  get {...}
  set {...}
}

public enum KMIPClientEncodings: Int32 {
  case etTTLV = 0
  case etXML = 1
  case etJSON = 2
}

@property (nonatomic,readwrite,assign,getter=encoding,setter=setEncoding:) int encoding;

- (int)encoding;
- (void)setEncoding :(int)newEncoding;

Default Value

0

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

Provides access to external signing and DC parameters.

Syntax

• Swift
• Objective-C

public var externalCrypto: ExternalCrypto {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=externalCryptoAsyncDocumentID,setter=setExternalCryptoAsyncDocumentID:) NSString* externalCryptoAsyncDocumentID;

- (NSString*)externalCryptoAsyncDocumentID;
- (void)setExternalCryptoAsyncDocumentID :(NSString*)newExternalCryptoAsyncDocumentID;

@property (nonatomic,readwrite,assign,getter=externalCryptoCustomParams,setter=setExternalCryptoCustomParams:) NSString* externalCryptoCustomParams;

- (NSString*)externalCryptoCustomParams;
- (void)setExternalCryptoCustomParams :(NSString*)newExternalCryptoCustomParams;

@property (nonatomic,readwrite,assign,getter=externalCryptoData,setter=setExternalCryptoData:) NSString* externalCryptoData;

- (NSString*)externalCryptoData;
- (void)setExternalCryptoData :(NSString*)newExternalCryptoData;

@property (nonatomic,readwrite,assign,getter=externalCryptoExternalHashCalculation,setter=setExternalCryptoExternalHashCalculation:) BOOL externalCryptoExternalHashCalculation;

- (BOOL)externalCryptoExternalHashCalculation;
- (void)setExternalCryptoExternalHashCalculation :(BOOL)newExternalCryptoExternalHashCalculation;

@property (nonatomic,readwrite,assign,getter=externalCryptoHashAlgorithm,setter=setExternalCryptoHashAlgorithm:) NSString* externalCryptoHashAlgorithm;

- (NSString*)externalCryptoHashAlgorithm;
- (void)setExternalCryptoHashAlgorithm :(NSString*)newExternalCryptoHashAlgorithm;

@property (nonatomic,readwrite,assign,getter=externalCryptoKeyID,setter=setExternalCryptoKeyID:) NSString* externalCryptoKeyID;

- (NSString*)externalCryptoKeyID;
- (void)setExternalCryptoKeyID :(NSString*)newExternalCryptoKeyID;

@property (nonatomic,readwrite,assign,getter=externalCryptoKeySecret,setter=setExternalCryptoKeySecret:) NSString* externalCryptoKeySecret;

- (NSString*)externalCryptoKeySecret;
- (void)setExternalCryptoKeySecret :(NSString*)newExternalCryptoKeySecret;

@property (nonatomic,readwrite,assign,getter=externalCryptoMethod,setter=setExternalCryptoMethod:) int externalCryptoMethod;

- (int)externalCryptoMethod;
- (void)setExternalCryptoMethod :(int)newExternalCryptoMethod;

@property (nonatomic,readwrite,assign,getter=externalCryptoMode,setter=setExternalCryptoMode:) int externalCryptoMode;

- (int)externalCryptoMode;
- (void)setExternalCryptoMode :(int)newExternalCryptoMode;

@property (nonatomic,readwrite,assign,getter=externalCryptoPublicKeyAlgorithm,setter=setExternalCryptoPublicKeyAlgorithm:) NSString* externalCryptoPublicKeyAlgorithm;

- (NSString*)externalCryptoPublicKeyAlgorithm;
- (void)setExternalCryptoPublicKeyAlgorithm :(NSString*)newExternalCryptoPublicKeyAlgorithm;

 

Default Value

""

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

FIPSMode Property (KMIPClient Module)

Reserved.

Syntax

• Swift
• Objective-C

public var fipsMode: Bool {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=FIPSMode,setter=setFIPSMode:) BOOL FIPSMode;

- (BOOL)FIPSMode;
- (void)setFIPSMode :(BOOL)newFIPSMode;

Default Value

False

Remarks

This property is reserved for future use.

InputBytes Property (KMIPClient Module)

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

Syntax

• Swift
• Objective-C

public var inputBytes: Data {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=inputBytes,setter=setInputBytes:) NSData* inputBytes;

- (NSData*)inputBytes;
- (void)setInputBytes :(NSData*)newInputBytes;

Remarks

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

InputFile Property (KMIPClient Module)

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

Syntax

• Swift
• Objective-C

public var inputFile: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=inputFile,setter=setInputFile:) NSString* inputFile;

- (NSString*)inputFile;
- (void)setInputFile :(NSString*)newInputFile;

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

The key to perform the operations on.

Syntax

• Swift
• Objective-C

public var key: CryptoKey {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=keyAlgorithm,setter=setKeyAlgorithm:) NSString* keyAlgorithm;

- (NSString*)keyAlgorithm;
- (void)setKeyAlgorithm :(NSString*)newKeyAlgorithm;

@property (nonatomic,readonly,assign,getter=keyBits) int keyBits;

- (int)keyBits;

@property (nonatomic,readwrite,assign,getter=keyHandle,setter=setKeyHandle:) long long keyHandle;

- (long long)keyHandle;
- (void)setKeyHandle :(long long)newKeyHandle;

@property (nonatomic,readwrite,assign,getter=keySubject,setter=setKeySubject:) NSData* keySubject;

- (NSData*)keySubject;
- (void)setKeySubject :(NSData*)newKeySubject;

 

Default Value

""

Remarks

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

KnownCertificates Property (KMIPClient Module)

Additional certificates for chain validation.

Syntax

• Swift
• Objective-C

public var knownCertificates: Array<Certificate> {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=knownCertCount,setter=setKnownCertCount:) int knownCertCount;

- (int)knownCertCount;
- (void)setKnownCertCount :(int)newKnownCertCount;

- (NSData*)knownCertBytes:(int)knownCertIndex;

- (long long)knownCertHandle:(int)knownCertIndex;
- (void)setKnownCertHandle:(int)knownCertIndex :(long long)newKnownCertHandle;

Default Value

""

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

KnownCRLs Property (KMIPClient Module)

Additional CRLs for chain validation.

Syntax

• Swift
• Objective-C

public var knownCRLs: Array<CRL> {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=knownCRLCount,setter=setKnownCRLCount:) int knownCRLCount;

- (int)knownCRLCount;
- (void)setKnownCRLCount :(int)newKnownCRLCount;

- (NSData*)knownCRLBytes:(int)knownCRLIndex;

- (long long)knownCRLHandle:(int)knownCRLIndex;
- (void)setKnownCRLHandle:(int)knownCRLIndex :(long long)newKnownCRLHandle;

Default Value

""

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.

KnownOCSPs Property (KMIPClient Module)

Additional OCSP responses for chain validation.

Syntax

• Swift
• Objective-C

public var knownOCSPs: Array<OCSPResponse> {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=knownOCSPCount,setter=setKnownOCSPCount:) int knownOCSPCount;

- (int)knownOCSPCount;
- (void)setKnownOCSPCount :(int)newKnownOCSPCount;

- (NSData*)knownOCSPBytes:(int)knownOCSPIndex;

- (long long)knownOCSPHandle:(int)knownOCSPIndex;
- (void)setKnownOCSPHandle:(int)knownOCSPIndex :(long long)newKnownOCSPHandle;

Default Value

""

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.

Objects Property (KMIPClient Module)

A list of objects returned by List .

Syntax

• Swift
• Objective-C

public var objects: Array<KMIPObject> {
  get {...}
}

@property (nonatomic,readonly,assign,getter=objectCount) int objectCount;

- (int)objectCount;

- (NSData*)objectBytes:(int)objectIndex;

- (BOOL)objectExtractable:(int)objectIndex;

- (NSData*)objectFingerprint:(int)objectIndex;

- (NSString*)objectKeyAlgorithm:(int)objectIndex;

- (int)objectKeyBits:(int)objectIndex;

- (int)objectKeyUsage:(int)objectIndex;

- (NSString*)objectObjectGroup:(int)objectIndex;

- (NSString*)objectObjectId:(int)objectIndex;

- (int)objectObjectType:(int)objectIndex;

- (BOOL)objectSensitive:(int)objectIndex;

- (int)objectSize:(int)objectIndex;

- (NSString*)objectSubject:(int)objectIndex;

- (NSString*)objectTimestamp:(int)objectIndex;

Default Value

""

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.

OutputBytes Property (KMIPClient Module)

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

Syntax

• Swift
• Objective-C

public var outputBytes: Data {
  get {...}
}

@property (nonatomic,readonly,assign,getter=outputBytes) NSData* outputBytes;

- (NSData*)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.

OutputFile Property (KMIPClient Module)

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

Syntax

• Swift
• Objective-C

public var outputFile: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=outputFile,setter=setOutputFile:) NSString* outputFile;

- (NSString*)outputFile;
- (void)setOutputFile :(NSString*)newOutputFile;

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

Specifies a password to authenticate to the KMIP server.

Syntax

• Swift
• Objective-C

public var password: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=password,setter=setPassword:) NSString* password;

- (NSString*)password;
- (void)setPassword :(NSString*)newPassword;

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

The proxy server settings.

Syntax

• Swift
• Objective-C

public var proxy: ProxySettings {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=proxyAddress,setter=setProxyAddress:) NSString* proxyAddress;

- (NSString*)proxyAddress;
- (void)setProxyAddress :(NSString*)newProxyAddress;

@property (nonatomic,readwrite,assign,getter=proxyAuthentication,setter=setProxyAuthentication:) int proxyAuthentication;

- (int)proxyAuthentication;
- (void)setProxyAuthentication :(int)newProxyAuthentication;

@property (nonatomic,readwrite,assign,getter=proxyPassword,setter=setProxyPassword:) NSString* proxyPassword;

- (NSString*)proxyPassword;
- (void)setProxyPassword :(NSString*)newProxyPassword;

@property (nonatomic,readwrite,assign,getter=proxyPort,setter=setProxyPort:) int proxyPort;

- (int)proxyPort;
- (void)setProxyPort :(int)newProxyPort;

@property (nonatomic,readwrite,assign,getter=proxyProxyType,setter=setProxyProxyType:) int proxyProxyType;

- (int)proxyProxyType;
- (void)setProxyProxyType :(int)newProxyProxyType;

@property (nonatomic,readwrite,assign,getter=proxyRequestHeaders,setter=setProxyRequestHeaders:) NSString* proxyRequestHeaders;

- (NSString*)proxyRequestHeaders;
- (void)setProxyRequestHeaders :(NSString*)newProxyRequestHeaders;

@property (nonatomic,readwrite,assign,getter=proxyResponseBody,setter=setProxyResponseBody:) NSString* proxyResponseBody;

- (NSString*)proxyResponseBody;
- (void)setProxyResponseBody :(NSString*)newProxyResponseBody;

@property (nonatomic,readwrite,assign,getter=proxyResponseHeaders,setter=setProxyResponseHeaders:) NSString* proxyResponseHeaders;

- (NSString*)proxyResponseHeaders;
- (void)setProxyResponseHeaders :(NSString*)newProxyResponseHeaders;

@property (nonatomic,readwrite,assign,getter=proxyUseIPv6,setter=setProxyUseIPv6:) BOOL proxyUseIPv6;

- (BOOL)proxyUseIPv6;
- (void)setProxyUseIPv6 :(BOOL)newProxyUseIPv6;

@property (nonatomic,readwrite,assign,getter=proxyUsername,setter=setProxyUsername:) NSString* proxyUsername;

- (NSString*)proxyUsername;
- (void)setProxyUsername :(NSString*)newProxyUsername;

 

Default Value

""

Remarks

Use this property to tune up the proxy server settings.

SignatureValidationResult Property (KMIPClient Module)

The signature validation result.

Syntax

• Swift
• Objective-C

public var signatureValidationResult: KMIPClientSignatureValidationResults {
  get {...}
}

public enum KMIPClientSignatureValidationResults: Int32 {
  case svtValid = 0
  case svtUnknown = 1
  case svtCorrupted = 2
  case svtSignerNotFound = 3
  case svtFailure = 4
  case svtReferenceCorrupted = 5
}

@property (nonatomic,readonly,assign,getter=signatureValidationResult) int signatureValidationResult;

- (int)signatureValidationResult;

Default Value

0

Remarks

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

This property is read-only.

SocketSettings Property (KMIPClient Module)

Manages network connection settings.

Syntax

• Swift
• Objective-C

public var socketSettings: SocketSettings {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=socketDNSMode,setter=setSocketDNSMode:) int socketDNSMode;

- (int)socketDNSMode;
- (void)setSocketDNSMode :(int)newSocketDNSMode;

@property (nonatomic,readwrite,assign,getter=socketDNSPort,setter=setSocketDNSPort:) int socketDNSPort;

- (int)socketDNSPort;
- (void)setSocketDNSPort :(int)newSocketDNSPort;

@property (nonatomic,readwrite,assign,getter=socketDNSQueryTimeout,setter=setSocketDNSQueryTimeout:) int socketDNSQueryTimeout;

- (int)socketDNSQueryTimeout;
- (void)setSocketDNSQueryTimeout :(int)newSocketDNSQueryTimeout;

@property (nonatomic,readwrite,assign,getter=socketDNSServers,setter=setSocketDNSServers:) NSString* socketDNSServers;

- (NSString*)socketDNSServers;
- (void)setSocketDNSServers :(NSString*)newSocketDNSServers;

@property (nonatomic,readwrite,assign,getter=socketDNSTotalTimeout,setter=setSocketDNSTotalTimeout:) int socketDNSTotalTimeout;

- (int)socketDNSTotalTimeout;
- (void)setSocketDNSTotalTimeout :(int)newSocketDNSTotalTimeout;

@property (nonatomic,readwrite,assign,getter=socketIncomingSpeedLimit,setter=setSocketIncomingSpeedLimit:) int socketIncomingSpeedLimit;

- (int)socketIncomingSpeedLimit;
- (void)setSocketIncomingSpeedLimit :(int)newSocketIncomingSpeedLimit;

@property (nonatomic,readwrite,assign,getter=socketLocalAddress,setter=setSocketLocalAddress:) NSString* socketLocalAddress;

- (NSString*)socketLocalAddress;
- (void)setSocketLocalAddress :(NSString*)newSocketLocalAddress;

@property (nonatomic,readwrite,assign,getter=socketLocalPort,setter=setSocketLocalPort:) int socketLocalPort;

- (int)socketLocalPort;
- (void)setSocketLocalPort :(int)newSocketLocalPort;

@property (nonatomic,readwrite,assign,getter=socketOutgoingSpeedLimit,setter=setSocketOutgoingSpeedLimit:) int socketOutgoingSpeedLimit;

- (int)socketOutgoingSpeedLimit;
- (void)setSocketOutgoingSpeedLimit :(int)newSocketOutgoingSpeedLimit;

@property (nonatomic,readwrite,assign,getter=socketTimeout,setter=setSocketTimeout:) int socketTimeout;

- (int)socketTimeout;
- (void)setSocketTimeout :(int)newSocketTimeout;

@property (nonatomic,readwrite,assign,getter=socketUseIPv6,setter=setSocketUseIPv6:) BOOL socketUseIPv6;

- (BOOL)socketUseIPv6;
- (void)setSocketUseIPv6 :(BOOL)newSocketUseIPv6;

 

Default Value

""

Remarks

Use this property to tune up network connection parameters.

TLSClientChain Property (KMIPClient Module)

The TLS client certificate chain.

Syntax

• Swift
• Objective-C

public var tlsClientChain: Array<Certificate> {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=TLSClientCertCount,setter=setTLSClientCertCount:) int TLSClientCertCount;

- (int)TLSClientCertCount;
- (void)setTLSClientCertCount :(int)newTLSClientCertCount;

- (NSData*)TLSClientCertBytes:(int)tLSClientCertIndex;

- (long long)TLSClientCertHandle:(int)tLSClientCertIndex;
- (void)setTLSClientCertHandle:(int)tLSClientCertIndex :(long long)newTLSClientCertHandle;

Default Value

""

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.

TLSServerChain Property (KMIPClient Module)

The TLS server's certificate chain.

Syntax

• Swift
• Objective-C

public var tlsServerChain: Array<Certificate> {
  get {...}
}

@property (nonatomic,readonly,assign,getter=TLSServerCertCount) int TLSServerCertCount;

- (int)TLSServerCertCount;

- (NSData*)TLSServerCertBytes:(int)tLSServerCertIndex;

- (NSString*)TLSServerCertFingerprint:(int)tLSServerCertIndex;

- (long long)TLSServerCertHandle:(int)tLSServerCertIndex;

- (NSString*)TLSServerCertIssuer:(int)tLSServerCertIndex;

- (NSString*)TLSServerCertIssuerRDN:(int)tLSServerCertIndex;

- (NSString*)TLSServerCertKeyAlgorithm:(int)tLSServerCertIndex;

- (int)TLSServerCertKeyBits:(int)tLSServerCertIndex;

- (int)TLSServerCertKeyUsage:(int)tLSServerCertIndex;

- (BOOL)TLSServerCertSelfSigned:(int)tLSServerCertIndex;

- (NSData*)TLSServerCertSerialNumber:(int)tLSServerCertIndex;

- (NSString*)TLSServerCertSigAlgorithm:(int)tLSServerCertIndex;

- (NSString*)TLSServerCertSubject:(int)tLSServerCertIndex;

- (NSString*)TLSServerCertSubjectRDN:(int)tLSServerCertIndex;

- (NSString*)TLSServerCertValidFrom:(int)tLSServerCertIndex;

- (NSString*)TLSServerCertValidTo:(int)tLSServerCertIndex;

Default Value

""

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.

TLSSettings Property (KMIPClient Module)

Manages TLS layer settings.

Syntax

• Swift
• Objective-C

public var tlsSettings: TLSSettings {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=TLSAutoValidateCertificates,setter=setTLSAutoValidateCertificates:) BOOL TLSAutoValidateCertificates;

- (BOOL)TLSAutoValidateCertificates;
- (void)setTLSAutoValidateCertificates :(BOOL)newTLSAutoValidateCertificates;

@property (nonatomic,readwrite,assign,getter=TLSBaseConfiguration,setter=setTLSBaseConfiguration:) int TLSBaseConfiguration;

- (int)TLSBaseConfiguration;
- (void)setTLSBaseConfiguration :(int)newTLSBaseConfiguration;

@property (nonatomic,readwrite,assign,getter=TLSCiphersuites,setter=setTLSCiphersuites:) NSString* TLSCiphersuites;

- (NSString*)TLSCiphersuites;
- (void)setTLSCiphersuites :(NSString*)newTLSCiphersuites;

@property (nonatomic,readwrite,assign,getter=TLSClientAuth,setter=setTLSClientAuth:) int TLSClientAuth;

- (int)TLSClientAuth;
- (void)setTLSClientAuth :(int)newTLSClientAuth;

@property (nonatomic,readwrite,assign,getter=TLSECCurves,setter=setTLSECCurves:) NSString* TLSECCurves;

- (NSString*)TLSECCurves;
- (void)setTLSECCurves :(NSString*)newTLSECCurves;

@property (nonatomic,readwrite,assign,getter=TLSExtensions,setter=setTLSExtensions:) NSString* TLSExtensions;

- (NSString*)TLSExtensions;
- (void)setTLSExtensions :(NSString*)newTLSExtensions;

@property (nonatomic,readwrite,assign,getter=TLSForceResumeIfDestinationChanges,setter=setTLSForceResumeIfDestinationChanges:) BOOL TLSForceResumeIfDestinationChanges;

- (BOOL)TLSForceResumeIfDestinationChanges;
- (void)setTLSForceResumeIfDestinationChanges :(BOOL)newTLSForceResumeIfDestinationChanges;

@property (nonatomic,readwrite,assign,getter=TLSPreSharedIdentity,setter=setTLSPreSharedIdentity:) NSString* TLSPreSharedIdentity;

- (NSString*)TLSPreSharedIdentity;
- (void)setTLSPreSharedIdentity :(NSString*)newTLSPreSharedIdentity;

@property (nonatomic,readwrite,assign,getter=TLSPreSharedKey,setter=setTLSPreSharedKey:) NSString* TLSPreSharedKey;

- (NSString*)TLSPreSharedKey;
- (void)setTLSPreSharedKey :(NSString*)newTLSPreSharedKey;

@property (nonatomic,readwrite,assign,getter=TLSPreSharedKeyCiphersuite,setter=setTLSPreSharedKeyCiphersuite:) NSString* TLSPreSharedKeyCiphersuite;

- (NSString*)TLSPreSharedKeyCiphersuite;
- (void)setTLSPreSharedKeyCiphersuite :(NSString*)newTLSPreSharedKeyCiphersuite;

@property (nonatomic,readwrite,assign,getter=TLSRenegotiationAttackPreventionMode,setter=setTLSRenegotiationAttackPreventionMode:) int TLSRenegotiationAttackPreventionMode;

- (int)TLSRenegotiationAttackPreventionMode;
- (void)setTLSRenegotiationAttackPreventionMode :(int)newTLSRenegotiationAttackPreventionMode;

@property (nonatomic,readwrite,assign,getter=TLSRevocationCheck,setter=setTLSRevocationCheck:) int TLSRevocationCheck;

- (int)TLSRevocationCheck;
- (void)setTLSRevocationCheck :(int)newTLSRevocationCheck;

@property (nonatomic,readwrite,assign,getter=TLSSSLOptions,setter=setTLSSSLOptions:) int TLSSSLOptions;

- (int)TLSSSLOptions;
- (void)setTLSSSLOptions :(int)newTLSSSLOptions;

@property (nonatomic,readwrite,assign,getter=TLSTLSMode,setter=setTLSTLSMode:) int TLSTLSMode;

- (int)TLSTLSMode;
- (void)setTLSTLSMode :(int)newTLSTLSMode;

@property (nonatomic,readwrite,assign,getter=TLSUseExtendedMasterSecret,setter=setTLSUseExtendedMasterSecret:) BOOL TLSUseExtendedMasterSecret;

- (BOOL)TLSUseExtendedMasterSecret;
- (void)setTLSUseExtendedMasterSecret :(BOOL)newTLSUseExtendedMasterSecret;

@property (nonatomic,readwrite,assign,getter=TLSUseSessionResumption,setter=setTLSUseSessionResumption:) BOOL TLSUseSessionResumption;

- (BOOL)TLSUseSessionResumption;
- (void)setTLSUseSessionResumption :(BOOL)newTLSUseSessionResumption;

@property (nonatomic,readwrite,assign,getter=TLSVersions,setter=setTLSVersions:) int TLSVersions;

- (int)TLSVersions;
- (void)setTLSVersions :(int)newTLSVersions;

 

Default Value

""

Remarks

Use this property to tune up the TLS layer parameters.

TrustedCertificates Property (KMIPClient Module)

A list of trusted certificates for chain validation.

Syntax

• Swift
• Objective-C

public var trustedCertificates: Array<Certificate> {
  get {...}
}

@property (nonatomic,readwrite,assign,getter=trustedCertCount,setter=setTrustedCertCount:) int trustedCertCount;

- (int)trustedCertCount;
- (void)setTrustedCertCount :(int)newTrustedCertCount;

- (NSData*)trustedCertBytes:(int)trustedCertIndex;

- (long long)trustedCertHandle:(int)trustedCertIndex;
- (void)setTrustedCertHandle:(int)trustedCertIndex :(long long)newTrustedCertHandle;

Default Value

""

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.

Username Property (KMIPClient Module)

The username to authenticate to the KMIP server.

Syntax

• Swift
• Objective-C

public var username: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=username,setter=setUsername:) NSString* username;

- (NSString*)username;
- (void)setUsername :(NSString*)newUsername;

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

Activates the specified server object.

Syntax

• Swift
• Objective-C

public func activate(objectId: String) throws -> Void

- (void)activate:(NSString*)objectId;

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

Imports a certificate to the KMIP server.

Syntax

• Swift
• Objective-C

public func add(addPrivateKey: Bool, group: String, activate: Bool) throws -> String

- (NSString*)add:(BOOL)addPrivateKey :(NSString*)group :(BOOL)activate;

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

Imports a key or keypair to the KMIP server.

Syntax

• Swift
• Objective-C

public func addKey(group: String, activate: Bool) throws -> String

- (NSString*)addKey:(NSString*)group :(BOOL)activate;

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

Sets or retrieves a configuration setting.

Syntax

• Swift
• Objective-C

public func config(configurationString: String) throws -> String

- (NSString*)config:(NSString*)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.

CustomRequest Method (KMIPClient Module)

Performs a custom request to the server.

Syntax

• Swift
• Objective-C

public func customRequest(data: Data) throws -> Data

- (NSData*)customRequest:(NSData*)data;

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

Deactivates the specified server object.

Syntax

• Swift
• Objective-C

public func deactivate(objectId: String) throws -> Void

- (void)deactivate:(NSString*)objectId;

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

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

Syntax

• Swift
• Objective-C

public func decrypt(objectId: String, algorithm: String, iv: Data, blockMode: String, paddingMethod: String, tagLength: Int32) throws -> Void

- (void)decrypt:(NSString*)objectId :(NSString*)algorithm :(NSData*)IV :(NSString*)blockMode :(NSString*)paddingMethod :(int)tagLength;

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

Performs an additional action.

Syntax

• Swift
• Objective-C

public func doAction(actionID: String, actionParams: String) throws -> String

- (NSString*)doAction:(NSString*)actionID :(NSString*)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;....

Common ActionIDs:

Encrypt Method (KMIPClient Module)

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

Syntax

• Swift
• Objective-C

public func encrypt(objectId: String, algorithm: String, iv: Data, blockMode: String, paddingMethod: String, tagLength: Int32) throws -> Void

- (void)encrypt:(NSString*)objectId :(NSString*)algorithm :(NSData*)IV :(NSString*)blockMode :(NSString*)paddingMethod :(int)tagLength;

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

Generates a new certificate on the KMIP server.

Syntax

• Swift
• Objective-C

public func generate(publicKeyId: String, activate: Bool) throws -> String

- (NSString*)generate:(NSString*)publicKeyId :(BOOL)activate;

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

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

Syntax

• Swift
• Objective-C

public func generateKey(keyAlgorithm: String, scheme: String, schemeParams: String, keyBits: Int32, group: String, activate: Bool) throws -> String

- (NSString*)generateKey:(NSString*)keyAlgorithm :(NSString*)scheme :(NSString*)schemeParams :(int)keyBits :(NSString*)group :(BOOL)activate;

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

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

Syntax

• Swift
• Objective-C

public func list(objectTypes: Int32, filter: String, offsetItems: Int32, maximumItems: Int32, freshOnly: Bool) throws -> Void

- (void)list:(int)objectTypes :(NSString*)filter :(int)offsetItems :(int)maximumItems :(BOOL)freshOnly;

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

Downloads a certificate from the KMIP server.

Syntax

• Swift
• Objective-C

public func read(objectId: String) throws -> Void

- (void)read:(NSString*)objectId;

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

Requests an attribute from an object.

Syntax

• Swift
• Objective-C

public func readAttribute(objectId: String, name: String) throws -> String

- (NSString*)readAttribute:(NSString*)objectId :(NSString*)name;

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

Downloads a key object from the KMIP server.

Syntax

• Swift
• Objective-C

public func readKey(objectId: String) throws -> Void

- (void)readKey:(NSString*)objectId;

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

Requests object information from the KMIP server.

Syntax

• Swift
• Objective-C

public func readObject(objectId: String) throws -> Void

- (void)readObject:(NSString*)objectId;

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

Removes the specified object from the server.

Syntax

• Swift
• Objective-C

public func remove(objectId: String) throws -> Void

- (void)remove:(NSString*)objectId;

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

Resets the component settings.

Syntax

• Swift
• Objective-C

public func reset() throws -> Void

- (void)reset;

Remarks

Reset is a generic method available in every class.

SetAttribute Method (KMIPClient Module)

Sets an attribute of an existing server-side object.

Syntax

• Swift
• Objective-C

public func setAttribute(objectId: String, name: String, value: String, delete_: Bool) throws -> Void

- (void)setAttribute:(NSString*)objectId :(NSString*)name :(NSString*)value :(BOOL)delete;

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

Replaces the data that has been prepared for sending out.

Syntax

• Swift
• Objective-C

public func setRequestBytes(value: Data) throws -> Void

- (void)setRequestBytes:(NSData*)value;

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

Alters the data received from the server in a response.

Syntax

• Swift
• Objective-C

public func setResponseBytes(value: Data) throws -> Void

- (void)setResponseBytes:(NSData*)value;

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

Signs the data using a key on the KMIP server.

Syntax

• Swift
• Objective-C

public func sign(objectId: String, algorithm: String, paddingMethod: String, hashAlgorithm: String, inputIsHash: Bool) throws -> Void

- (void)sign:(NSString*)objectId :(NSString*)algorithm :(NSString*)paddingMethod :(NSString*)hashAlgorithm :(BOOL)inputIsHash;

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

Verifies digitally signed data.

Syntax

• Swift
• Objective-C

public func verify(objectId: String, algorithm: String, paddingMethod: String, hashAlgorithm: String, inputIsHash: Bool) throws -> Void

- (void)verify:(NSString*)objectId :(NSString*)algorithm :(NSString*)paddingMethod :(NSString*)hashAlgorithm :(BOOL)inputIsHash;

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

Provides information about errors during KMIP operations.

Syntax

• Swift
• Objective-C

func onError(errorCode: Int32, description: String)

- (void)onError:(int)errorCode :(NSString*)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 Module)

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

Syntax

• Swift
• Objective-C

func onExternalSign(operationId: String, hashAlgorithm: String, pars: String, data: String, signedData: inout String)

- (void)onExternalSign:(NSString*)operationId :(NSString*)hashAlgorithm :(NSString*)pars :(NSString*)data :(NSString**)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: 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 Module)

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

Syntax

• Swift
• Objective-C

func onNotification(eventID: String, eventParam: String)

- (void)onNotification:(NSString*)eventID :(NSString*)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.

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

Request Event (KMIPClient Module)

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

Syntax

• Swift
• Objective-C

func onRequest(requestData: Data)

- (void)onRequest:(NSData*)requestData;

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

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

Syntax

• Swift
• Objective-C

func onResponse(responseData: Data)

- (void)onResponse:(NSData*)responseData;

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

Fires when a remote TLS party requests a client certificate.

Syntax

• Swift
• Objective-C

func onTLSCertNeeded(host: String, caNames: String)

- (void)onTLSCertNeeded:(NSString*)host :(NSString*)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 Module)

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

Syntax

• Swift
• Objective-C

func onTLSCertValidate(serverHost: String, serverIP: String, accept: inout Bool)

- (void)onTLSCertValidate:(NSString*)serverHost :(NSString*)serverIP :(int*)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 Module)

Fires when a TLS handshake with Host successfully completes.

Syntax

• Swift
• Objective-C

func onTLSEstablished(host: String, version: String, ciphersuite: String, connectionId: Data, abort: inout Bool)

- (void)onTLSEstablished:(NSString*)host :(NSString*)version :(NSString*)ciphersuite :(NSData*)connectionId :(int*)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 Module)

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

Syntax

• Swift
• Objective-C

func onTLSHandshake(host: String, abort: inout Bool)

- (void)onTLSHandshake:(NSString*)host :(int*)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.

TLSPSK Event (KMIPClient Module)

Notifies the application about the PSK key exchange.

Syntax

• Swift
• Objective-C

func onTLSPSK(host: String, hint: String)

- (void)onTLSPSK:(NSString*)host :(NSString*)hint;

Remarks

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

Reports the graceful closure of a TLS connection.

Syntax

• Swift
• Objective-C

func onTLSShutdown(host: String)

- (void)onTLSShutdown:(NSString*)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

Encapsulates an individual X.509 certificate.

Remarks

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

Fields

Constructors

public init(stream: )

public init()

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

public init()

CryptoKey Type

This container represents a cryptographic key.

Remarks

This type is a universal placeholder for cryptographic keys.

Fields

Constructors

public init()

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

public init()

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

public init()

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

public init()

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 init()

SocketSettings Type

A container for the socket settings.

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

public init()

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

public init()

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 init()

Config Settings (KMIPClient Module)

KMIPClient Config Settings