CC ACSP Java Programmer's Guide

Used Classes

Configuration of a PKCS #11 Provider

See reference [1] for the JCE pkcs11 provider. Here is used the ”Sun PKCS#11” provider, which is implemented by the main class sun.security.pkcs11.SunPKCS11. The provider uses a PKCS11 dynamic link library (DLL). The provider uses a customized configuration file, which here is called java-cca.cnf, and can handle several DLL's at the same time.

Using a Static Provider Configuration:

Add a line in the file %JAVA_HOME%/lib/security/java.security as follows:

security.provider.n=sun.security.pkcs11.SunPKCS11 /path-to/java-cca.cnf

In this n is the next number in the series, and path-to can be any path as well as the name of the file.

Example of java-cca.cnf:

name=CCA-0
library={full path to}/acsp-pkcs11_ep11.dll
slot=0

Or a Dynamic Configuration:

A dynamic configuration is done in code alone. It requires the name of the DLL (full path) and slot ID, if different from slot 0.

Java Example for Oracle/SUN PKCS#11:

String PROVIDER_SUNPKCS11 = "sun.security.pkcs11.SunPKCS11";
Class<Provider> clazz = (Class<Provider>)Class.forName(PROVIDER_SUNPKCS11);
Constructor<Provider> ctor = clazz.getConstructor(new Class[] {InputStream.class});
String DLLname = "path/pkcs11_cca.dll";
String slot = "0";

// Initialize for SunPKCS11 implementation
String conf = "name = CCA-0" + "\nlibrary=" + DLLname + "\nslot="+slot;
ByteArrayInputStream config = new ByteArrayInputStream(conf.getBytes());
p = (Provider)ctor.newInstance(new Object[] {conf});

// Next add the provider as the first in the list:
Security.insertProviderAt(p, 1);

Java example for IBM PKCS#11:

String PROVIDER_IBMPKCS11 = "com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl";
Class<Provider> clazz = (Class<Provider>)Class.forName(PROVIDER_IBMPKCS11);
Constructor<Provider> ctor = clazz.getConstructor(new Class[] {BufferedReader.class});
String DLLname = "path/pkcs11_cca.dll";
String slot = "0";

// Initialize for IbmPKCS11 implementation
String conf = "name = CCA-0" + "\nlibrary=" + DLLname + "\nslot="+slot;
BufferedReader config = new BufferedReader(new StringReader(conf));
p = (Provider)ctor.newInstance(new Object[] {conf});

Loading Key Store

A key store must be loaded before it can be used. This is the only difference (in application code) between a Java key store (JKS) and a PKCS #11 key store.

There are two ways to get the key store, either

• by type - when the provider is defined as the first provider in the list of providers with pkcs11 support
• by name - Name as defined in configuration, see later.

Getting Key Store by Type

KeyStore ks= KeyStore.*getInstance*(”pkcs11”);
or
KeyStore ks= KeyStore.*getInstance*(”JKS”);

Getting Key Store by Name

Provider p = Security.getProvider("SunPKCS11-CCA-0");
KeyStore ks= KeyStore.getInstance("pkcs11", p);

For JKS key stores a file name and path to the JKS file and a password, the following statements are used:

FileInputStream s = new FileInputStream(fileName);
ks.load(s, ivKeystorePassword);

For PKCS #11 key stores a service name and password provider are used as follows:

ks.load(**this**);

where this implements the interface KeyStore.LoadStoreParameter. The only method to implement is the following:

@Override
public ProtectionParameter getProtectionParameter() {
  return new KeyStore.PasswordProtection(ivKeystorePassword);
}

After this, reading the key-store and doing cryptographic operations are the same for both types of key-store.

Listing Entries in a Key Store

Once the key store is loaded with the objects it should contain, and when access has been granted, its entries can be listed by calling the aliases() method as in the following example:

public void list(KeyStore keystore) throws ... {
  Enumeration<String> aliases = keystore.aliases();
  while (aliases.hasMoreElements()) {
    String a = aliases.nextElement();
    Entry k = keystore.getEntry(a, getProtectionParameter());
    String sName = k.getClass().getName();
    println("alias="+String.format("%1$-24s", a)+", type="+ sName.substring(sName.indexOf('$')+1));
  }
}

Reading and Using Key store Entries

When an alias is known, the entry can be read directly. Its use depends on the type of entry. The code looks like the following example:

public void readExample(String alias, KeyStore keystore) {
  Entry k=getEntry(alias,keystore);
  if(k instanceof PrivateKeyEntry){
    PrivateKey pk=((PrivateKeyEntry)k).getPrivateKey();
    if(pk.getAlgorithm().equals("DSA")){
      byte[]signature = ivLastSignature = 
               privateKeySign(pk, clearText, "SHA1withDSA");
    }
			
    Certificate[] chain=keystore.getCertificateChain(alias);
    // Certificates may need to be reordered
    PublicKey key=chain[chain.length-1].getPublicKey(); 
    //Example:publicKeyVerify(key,clearText,signature,algorithm);
  }else
  if(k instanceof TrustedCertificateEntry){
    Certificate c = ((TrustedCertificateEntry)k).getTrustedCertificate();
    PublicKeykey=c.getPublicKey();
    if(key.getAlgorithm().equals("DSA")){
      boolean verified = 
          publicKeyVerify(key, clearText, ivLastSignature, "SHA1withDSA");
    }			
  }else
  if(k instanceof SecretKeyEntry){
    SecretKey sk=((SecretKeyEntry)k).getSecretKey();
    if(sk.getAlgorithm().equals("AES")){
      byte[] encrypted = secretKeyEncrypt(sk, new byte[16], clearText, 0,
                     clearText.length, "AES/CBC/PKCS5Padding");
    }
  }
}

Encrypting with a Secret Key

The following example code implements a method which encrypts data and returns an array of encrypted bytes:

public byte [] secretKeyEncrypt(SecretKey sk, byte [] iv, byte [] input,int inputOffset, int inputLen, String transformation) {
  IvParameterSpec ivp = new IvParameterSpec(iv);
  // ivProvider as loaded above
  Cipher cipher = Cipher.getInstance(transformation, ivProvider);
  cipher.init(Cipher.ENCRYPT_MODE, sk, ivp);		
  return cipher.doFinal(input, inputOffset, inputLen);
}

Private Key Signing and Public Key Verifying Operations

The following example code creates a signature with a private key**:**

byte [] privateKeySign(PrivateKey pk, byte [] data, String algo) {
  Signature s = Signature.getInstance(algo, ivProvider);
  s.initSign(pk);
  s.update(data);
  return s.sign();
}

The following example code verifies a signature with a public key:

boolean publicKeyVerify(PublicKey pk, byte [] data, byte [] signature, String algo) {
  Signature s = Signature.getInstance(algo, ivProvider);
  s.initVerify(pk); // also has a method with a certificate
  s.update(data);
  return s.verify(signature);		
}

The examples are independent of provider. However, if the code does not use the provider parameter then the provider must be the first provider in the list, see Configuration of a PKCS #11 Provider.

The following example code shows to to use a default provider:

s = Signature.getInstance("SHA1withRSA"); // no provider, uses default provider

Generating Key Pairs

Key pairs can be generated with a KeyPairGenerator.

A key pair is generated by calling the generateKeyPair() method of an initialized KeyGenerator.

Examples of initializing a KeyGenerator as follows:

public KeyPair generateRSAKeyPair(int bitSize) {
  KeyPairGenerator generator = 
      KeyPairGenerator.getInstance( "RSA", ivProvider );
  AlgorithmParameterSpec params = 
      new RSAKeyGenParameterSpec(bitSize, RSAKeyGenParameterSpec.F4);
  generator.initialize(params);
  return generator.generateKeyPair();
}

// EC example:
KeyPairGenerator generator = getKeyPairGenerator("EC");
AlgorithmParameterSpec params = new ECGenParameterSpec("secp256r1");
generator.initialize(params);

// DSA example:
KeyPairGenerator generator = getKeyPairGenerator("DSA");
generator.initialize(bitSize);

Note: Keys generated with JCE will be session keys with PKCS#11.

The following algorithms are supported:

Generating Secret Keys

Secret keys are generated with a KeyGenerator (the same way as key pairs).

A secret key is generated by calling the generateKey() method of an initialized KeyGenerator.

public SecretKey generateSymKey(String algorithm, int keySize) {
  KeyGenerator generator = getKeyGenerator(algorithm);
  generator.init( keySize );
  return generator.generateKey();
}

JCE/pkcs11 supports the following algorithms and sizes:

For more details see: http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#Cipher

Creating Keys

A key that is known in a byte array can be converted into a SecretKey without having to go through a provider-based SecretKeyFactory or KeyGenerator as in the following example:

SecretKey k = new SecretKeySpec(CCAUtil.X2B("29fcbbc506989671909510f08c723f51de5836aa58a17cb7d098bdc5757fc0ce"), "AES");

Storing Keys

As mentioned previously, keys are created or generated as session keys. Keys are added to a key-store by calling the method setEntry() as in the following example:

public void addSecretKey(KeyStore ks, SecretKey k, String alias) {
  KeyStore.SecretKeyEntry skEntry = new KeyStore.SecretKeyEntry(k);
  ks.setEntry(alias, skEntry, null);
}

To add a PrivateKey is a bit more complicated as a certificate is required. How to create such certificate is out of scope of this document. See the following example of the concept:

Certificate [] certs= …;
KeyPair kp = …;
KeyStore ks = …;
KeyStore.PrivateKeyEntry pkEntry = new KeyStore.PrivateKeyEntry(kp.getPrivate(), certs);
ks.setEntry(alias, pkEntry, null);

Finally, when objects have been added to the key store, the key-store may be saved by calling its store() method:

ks.store(null);

Message Authentication Code

The key must be a generic secret key. Also the CKA_SIGN attribute must be true. These keys do not support encryption or decryption, they can be used in HMAC operations.

Example:

SecretKey k = …;
Mac hm = Mac.getInstance(algorithm, ivProvider);
hm.init(k);
mac = hm.doFinal(clearText);

For more information, see:

http://docs.oracle.com/javase/8/docs/api/javax/crypto/Mac.html

For supported algorithms, see “Provider Services and Algorithms” below.

CBC-MAC

PKCS#11 has MAC algorithms for AES and DES, and these are not supported through JCE/PKCS11. The MAC can be calculated by a CBC operation as in the following example:

public byte [] secretKeyMac(SecretKey sk, byte [] iv, byte [] message) {
byte [] mesPadded = zeroPad0(message, iv.length);
AlgorithmParameterSpec ivAcps = new IvParameterSpec(iv);

  byte [] mac = secretKeyEncrypt( sk, iv, mesPadded, 0, 
             mesPadded.length, "AES/CBC/NoPadding"); // or DES
  // return the last half block
  return Arrays.copyOfRange(mac, mac.length-iv.length, 
             mac.length-iv.length/2); 
}

Provider Services and Algorithms

A provider will provide a list of services. These can be listed as in the following example:

Provider provider = ...
Set<Provider.Service> s = provider.getServices();

for (Service x:s) {
  StringBuffer sb = new StringBuffer();
  sb.append("Service type="+x.getType()+", algorithm="+x.getAlgorithm());
  println(sb.toString());	
}

Sorted output for Provider=sun.security.pkcs11.SunPKCS11, name=SunPKCS11-CCCPKCS11 as listed in the table below:

Use Java keytool to Generate and List Objects

keytool is a command line utility for operating key-stores. Key-stores can be both java key-stores (JKS) and PKCS#11 key-stores.

On Linux we can use a small shell script like in the following example:

#
# Uses Java keytool to generate keys and certificates
# Example: ktool.sh -list
#
# Find out where the configuration file is...
if [ -d test ]; then
PROJ=$PWD
else
PROJ=$PWD/..
fi

## Check absolute path in ep11.cnf
CNF=$PROJ/config/ep11.cnf
PRVCLS=sun.security.pkcs11.SunPKCS11
#Note! The following is for IBM JRE provider
#PRVCLS=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl
keytool -storetype pkcs11 -storepass zaqwsx -providerclass $PRVCLS -providerarg $CNF "$@"

Keytool uses the same configuration file as above; see Configuration of a PKCS #11 Provider.

Storepass is not used when using the CC ACSP client; but it must be specified.

Now we can use this script to list the content using the following command:

$ ./ktool.sk -list

and to generate an EC key pair as in the following example:

$ algo=EC
$ keysize=256
$ label=testlabel
$ ./ktool.sh -genkeypair -keyalg $algo -keysize $keysize -alias $label -validity 3660 -dname "CN=${label} ACSP, OU=CCCC, O=IBM Denmark, L=Copenhagen, ST=Unknown, C=dk"

For options and limitations see the keytool documentation

Using PKCS#11 Key Stores as TLS Trust store and Key store

It is possible to setup SSL/TLS to use a PKCS11 trust store and key store, see also the PKCS#11 guide referenced in the above link.

The trust-store can be configured with Java VM arguments:

-Djavax.net.ssl.trustStoreType=PKCS11 -Djavax.net.ssl.trustStore=NONE

The key-store can be configured with Java VM arguments like in the following example:

-Djavax.net.ssl.keyStoreType=PKCS11 -Djavax.net.ssl.keyStore=NONE

For programs that cannot load the pkcs11 provider dynamically the pkcs11 provider should be added to the JRE provider list. See Configuration of a PKCS #11 Provider.

Note: The same pkcs11 key store is used for trust and private keys.

Differences between Oracle and IBM Java

UDF development for local execution

As of release 2.1.4 of the CC ACSP developer package, a UDF can be configured to execute locally. Executing a UDF locally means the UDFCALL defined function is executed in a local developer environment as oppose to executing on the CC ACSP server. This implies the developer environment to support jCCA natively or via the CC ACSP client. In this manual we show how to execute a UDF locally via the CC ACSP client. It requires two steps:

• Configure the CC ACSP client as jCCA provider
• Write code to enable local execution

Configuring the CC ACSP client as jCCA provider

As with normal execution we configure the CC ACSP Java Client as the jCCA provider. The jcca.properties file configures jCCA as described in Using CC ACSP client with jCCA. To setup the CC ACSP client as provider of jCCA we set the parameter cca-root-class to the CC ACSP client as shown in the following statement:

cca-root-class=com.ibm.acsp.client.protocol.cca.ProtocolCcaClient

Note: This is the default setup in the CC ACSP developer package.

Write code to enable local execution

To tell jCCA to execute the UDF function locally we have to call a method in the static jCCA class CCACommon which has to be imported with:

import com.ibm.crypto.hardware.common.CCACommon;

To enable local execution, we have to pass an instance of the UdfCallExecutor which is provided by the CC ACSP client. This is imported with:

import com.ibm.acsp.client.udf.UdfCallExecutor;

The CCACommon method setUdfExecutor call looks as follows:

CCACommon.setUdfExecutor(new UdfCallExecutor());

With this setup the UDFCALL function will be executed locally, and the need for deploying the UDF to a CC ACSP server is removed. Now UDFCALL can be instantiated as described Calling a UDF from the CC ACSP Java Client.

The only difference on local UDF execution contra normal execution, is that one line of code on the client-side program, where the UDF executor utility class is instantiated. Remove that one line of code from the client-side program to execute normally on a CC ACSP server.

Naming the UDF Function Class

The UDF package and class should be named uniquely overlap any CC ACSP provided packages. In general this means that customized UDFs must not not start with:

*com.ibm.acsp...*which are the name space of CC ACSP.

Typically the reverse name of the internet domain name for a company are used. Examples:

• A company with domain name kyndryl.com could name a UDF as com.kyndryl.finance.Procedure1
• A company with domain name landing.co.uk could name a UDF as uk.co.landing.EncryptAll

Adding a New UDF Library to the CC ACSP Server

Please carry out the following steps to add a new Java library to the CC ACSP server:

• Create a jar file with the compiled Java code, for example by using Maven, Ant or Eclipse.
• Copy the jar file to the ./lib directory of the CC ACSP server
• Restart the CC ACSP server (stop/start)

Updating a UDF Library to the CC ACSP Server

Please do the following 3 steps to update an existing Java library to the CC ACSP server:

• Copy the updated jar file to the ./lib directory of the CC ACSP server, replacing the old one.
• Restart the CC ACSP server (stop/start)

Updating the CC ACSP server Authorization for UDF Execution

The authorization resources for the UDF class must be defined and authorized if the authorization has been enabled. If the authorization feature is not enabled, this step can be omitted.

The deployed UDF class and method must be defined and authorized in the Authorization System using a named UDF resource with the following syntax:

acsp.udfcall.<package-name>.<class-name>

The resource name must be defined in the authorization system, and the client user ID or client group ID must be given permission to the resource name with at least read access.

Client Control and Host Reservation Java package name and classes

The Host Reservation class is called: com.ibm.acsp.ClientController

Note! The old ACSP 1.5 class called ACSPClientController has been removed, the ClientController should be used instead.

All functions in the client control and host reservation API is accessed through this class in the CC ACSP Java Client.

The ClientController class is a singleton instance which is accessed by using its public static getInstance method.

Get Host List

Synopsis

public String[] getHostList()

Description

The getHostList function is used to query the CC ACSP Java Client for the list of available hosts. This can be used to iterate over each available host and perform a specific sequence of CCA calls on each host.

The host list is generated based on the client.connect and client.backup parameters.

Each parameter is a list of hosts and services. The host addresses are resolved as defined by the host definition.

Return value

Returns an array of strings, representing each available host.

Set Host Reservation

Synopsis

public boolean setHostReservation(String hostname)

Description

The setHostReservation function is used to reserve the use of a specific host for subsequent CCA calls. The reservation is specific to the thread, and does not affect the execution of calls which are made by other threads.

The provided hostname is validated against the hosts specified in the configuration file. If the provided hostname is not found, the reservation fails. The validation of the hostname is string comparison which is not case sensitive. This means that if a domain-name is specified in the configuration file, the corresponding IP address will not be accepted.

Call the releaseHostReservation function to end the reservation.

Note that a host reservation cannot be made, when another reservation is in effect. Attempting to do so, will cause the reservation to fail.

Return Value

On successful completion, this function returns true. If the function fails, it returns false.

Get Host Reservation

Synopsis

public String getHostReservation()

Description

The getHostReservation function is used to retrieve the host name of the host that was previously reserved.

Return Value

The hostname of the reserved host, or null if no host is reserved.

Release Host Reservation

Synopsis

public boolean releaseHostReservation()

Description

Call this function to release the current host reservation for the calling thread.

Upon successful completion, subsequent CCA calls made by the thread are included in the normal load-balancing performed by the CC ACSP Java Client.

Return Value

On successful completion, this function returns true. If the function fails, it returns false.

Host Reservation Examples

Reserving a Host

To direct a sequence of jCCA calls to a specific host (CC ACSP server), call the setHostReservation function as in the following example.

ClientController acspCtrl=ClientController.getInstance();
if (!acspCtrl.setHostReservation(host)){
    System.out.println("Reservation of host "+host+" failed");
    return;
}

Releasing a Host Reservation

To stop sending jCCA calls to a specific host (CC ACSP server), call the releaseHostReservation function as in the following example.

ClientController acspCtrl=ClientController.getInstance();
if (!acspCtrl.releaseHostReservation()){
    System.out.println("Release of host failed");
    return;
}

Retrieving the Current Host Reservation

The host reservation API provides the getHostReservation function for retrieving the current host-reservation as in the following example.

ClientController acspCtrl=ClientController.getInstance();
String reservation=acspCtrl.getHostReservation();
if (reservation==null){
    System.out.println("Reserved host: NONE");
} else {
    System.out.println("Reserved host: "+reservation);
}

Retrieving the Host List

The host reservation API provides the getHostList function for retrieving the current host list as in the following example.

ClientController acspCtrl=ClientController.getInstance();
String[] hostlist = acspCtrl.getHostList();

Iterating the Host List

Once the host list has been obtained, it can be used to iterate over the available hosts.

For each entry in the host list, the host name should be passed to the setHostReservation function before any jCCA verbs are called.

Before ending the iteration, the host reservation should be released as in the following example. If this is not done, the host reservation at the start of the next iteration will fail.

ClientController acspCtrl=ClientController.getInstance();
String[] hostlist = acspCtrl.getHostList();
for(int index=0;index<hostlist.length;index++){
    if (!acspCtrl.setHostReservation(host)){
        System.out.println("Reservation of host "+host+"failed");
        return;
    }
    try {
        //Call any sequence of jCCA verbs,
        //to have them executed on the reserved host.
    } finally {
        //Make sure that we release the host reservation,
        //even if an exception is thrown
        acspCtrl.releaseHostReservation();
    }
}

SetSslKeyStorePassword

Synopsis

public void setSslKeyStorePassword(String password)

Description

Call this function to set the JKS key-store password, of the key-store specified in the acsp.properties file by the “ssl.keyStore” property.

A call to this method will override the password specified by the “ssl.keyStorePassword” property in the acsp.properties file.

ClientController.getInstance().setSslKeyStorePassword("useThisPassword");

A call to this method will override the password specified by the “ssl.keyStorePassword” property in the acsp.properties file.

Note! The password must be set before a connection to the host is established, which is typically done when the first CCA verb is called.

GetSslKeyStorePassword

Synopsis

public String getSslKeyStorePassword()

Description

Call this function to get the JKS key-store password which has been set either by the getSslKeyStorePassword() method or the “ssl.keyStorePassword” property specified in the acsp.properties file.

String pw = ClientController.getInstance().getSslKeyStorePassword();

CloseConnectionPool

Synopsis

public boolean closeConnectionPool()

Description

Call this function to close all active connections to the specified server(s). This is normally not required, but can be used if application program does not call exit which automatically closes the connections.

If any CCA or ICSF verbs are called after this operation, then new connections to the CC ACSP server(s) will be established.

if (ClientController.getInstance().closeConnectionPool()) {
    System.out.println("done");
} else {
    System.out.println("did not do it");
}

GetConnectionList

Synopsis

public List<ServerData> getConnectionList()

Description

Call this function to get a List of connections to the specified CC ACSP server(s). ServerData is a communication object which holds diverse information about s connected server.

List<ServerData> connections =
    ClientController.getInstance().getConnectionList<>();
for (ServerData sd : connections) {
    System.out.println(sd);
}

AgileClient Sample Description

AgileClient demonstrates how to manage UDF properties on the server side and provides an example how it can be used to provide extra flexibility in configuring and controlling digital signature generation and verification. At the same time it also provides an example of handling the user defined reason codes on the client side.

The AgileClient class has the following methods defined:

• main:

The main method sets up local execution of the UDF, by instantiating an object of the UdfCallExecutor class and pass it to the setter method of the CCACommon class provided by jCCA. An object of AgileClient class is instantiated for user interaction using the command line.

• interact:

The interact method basically is a loop of reading the user commands and processing them. Two special commands are defined to quit the loop and shut down the program - 'x', 'q'.

• readCommand:

A method where user input is awaited and user command string is returned after one has been entered.

• processCommand:

This method handles the user commands that have been read from the command line. It treats the first token of the input as the command itself and the second as an option for that command. If it fails to understand the command, it will output the list of all commands available. PKA key generation and deletion, use value switching is also executed inside this method.

• sayCCAException:

sayCCAException method is used to handle the reason codes returned within a CCAException that might be thrown while the server side code is called.

• execute:

The execute function is a UDF utility function that encapsulates the UDFCALL pseudo-verb. It executes a UDF and demonstrates how data can be send using the TLVContainer class provided by the jCCA framework.

• listProperties:

A method that will output all the UDF properties as key-value pairs.

• getProp:

A method that will output a value of a property.

• setProp:

A method that will change a value of a property. It can also be used to delete a property by providing an empty string as the new value.

• copyProp:

copyProp method copies a complete property set.

• getUseValues:

A method that will list all the encryption scheme options which are stored inside 'use.values' UDF property.

• checkUseValue:

A method to check whether specific use value is present in 'use.values' UDF property.

• sign:

A method that given data in a form of a byte array, generates a digital signature associated to the data along with the use value.

• verify:

A method that given data, use value and signature, verifies the data against the signature.

• checkKeys:

A method that lists PKA keys referenced by the use values.

AgileClient Sample Code

package acsp.samples;

import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import com.ibm.acsp.client.udf.UdfCallExecutor;
import com.ibm.crypto.hardware.api.TargetInfo;
import com.ibm.crypto.hardware.common.CCACommon;
import com.ibm.crypto.hardware.common.CCAException;
import com.ibm.crypto.hardware.common.CCAUtil;
import com.ibm.crypto.hardware.generic.UDFCALL;
import com.ibm.crypto.utility.TLVContainer;
import com.ibm.crypto.utility.UtilMethods;

/**
 * Communication client to send command input to a peer and display whatever replies returned.
 * The peer is expected to always return a response to each single line request.
 */
public class AgileClient extends UtilMethods
{

    // Fully qualified class name of UDFControl
    private static String ivUdfClass 	     = "";
	  private static final String UDFCLASS_LOCAL = "acsp.samples.udf.AgileUDF";
	  private static final String UDFCLASS_SERVER  = "com.ibm.acsp.server.udf.AgileUDF";

    private byte[] signature = null;
    private String with = null;

    private byte[] signtext = CCAUtil.S2B("There is plasters on my fingers");

   /**
     * Utility function to execute an UDF.
     * @param data the argument data which should be sent to the UDF
     * @param operations Array of names of the operations to perform inside the called UDF
     * @return The resulting UDFCALL after execution
     * @throws CCAException in case of CCA error
     */
    private static TLVContainer.ElementList execute(byte[] data, String ... operations) throws CCAException {
        UDFCALL call = new UDFCALL();
        call.setFunction(ivUdfClass);
        call.addRules(operations);
        if (data!=null) { 
            call.setDataIn(data);
        }
        call.setDataOutLength(4096);	// size enough
        call.execute();
        if(call.getReturnCode() > 0) {  // check for failures after executing via UDFCallExecutor
			throw new CCAException(call.getReturnCode(), call.getReasonCode());
		}
        return TLVContainer.decode(call.getDataOut());
    }


    private void checkKeys() {
        TLVContainer.ElementList res = null;
        try {
            res = execute(null,"CHECK");
            List<String> list = new ArrayList<>();
            for (int i=0;i<res.size();i++) {
                list.add(res.getString(i));
            }
            Collections.sort(list);
            say("List keys referenced by use values - count(%s):%n",list.size());
            for (String s : list) {
                say("  %s%n",s);
            }
        } catch (CCAException e) {
            say("CHECK function failed with: %s%n",sayCCAException(e));
        }
    }

    private void listProperties() {
        TLVContainer.ElementList res = null;
        try {
            res = execute(null,"LISTPROP");
            List<String> list = new ArrayList<>();
            for (int i=0;i<res.size();i++) {
                list.add(res.getString(i));
            }
            Collections.sort(list);
            say("List contents of properties:%n");
            for (String s : list) {
                say("  %s%n",s);
            }
        } catch (CCAException e) {
            say("LISTPROP function failed with: %s%n",sayCCAException(e));
        }
    }

    private String getProp(String key) {
        TLVContainer con = new TLVContainer();
        con.addElement(key);

        say("Getting property key: %s%n",key);
    	
        TLVContainer.ElementList res = null;
        try {
            res = execute(con.encode(),"GETPROP");
            String value = res.getString(0); 
            say("  value of property key %s is '%s' %n",key,value);
            return value;
        } catch (CCAException e) {
            say("GETPROP function failed with: %s%n",sayCCAException(e));
        }
         return "";
    }

    private void copyProp(String from,String to){
        TLVContainer con = new TLVContainer();
        con.addElement(from);
        con.addElement(to);
        say("Copying property set '%s.*' to property set '%s.*'%n",from,to);
    	
        try {
            execute(con.encode(),"COPYPROP");
        } catch (CCAException e) {
            String msg = e.toString();
            if (e.isRR(32, 1833)) {
                msg = String.format("from use set(%s) is not found",from);
            } else
            if (e.isRR(32, 1835)) {
                msg = String.format("to use set(%s) is not found",to);
            }
            say("COPYPROP function failed with: %s%n",msg);
        }
    }

    private void setProp(String key,String value){
        TLVContainer con = new TLVContainer();
        con.addElement(key);
        con.addElement(value);

        if (value.isEmpty()) {
            say("Deleting property key: %s%n",key);
        } else {
            say("Setting property key: %s to '%s'%n",key,value);
        }
    	
        try {
            execute(con.encode(),"SETPROP");
        } catch (CCAException e) {
            say("SETPROP function failed with: %s%n",sayCCAException(e));
        }
    }

    private TLVContainer.ElementList sign(byte[] data){
        TLVContainer con = new TLVContainer();
        con.addElement(data);
        TLVContainer.ElementList res = null;
        try {
            res = execute(con.encode(),"SIGN");
            signature = res.getBytes(0);
            with = res.getString(1);
            say("Signing data with key: %s%n",with);
            String signatureText = CCAUtil.B2X(signature);
            say("Signature is: %s%n", signatureText);
        } catch (CCAException e) {
            say("SIGN function failed with: %s%n",sayCCAException(e));
        }
        return res;
    }

    private TLVContainer.ElementList verify(String meta, byte[] data, byte[] signature) {
        TLVContainer con = new TLVContainer();
        TLVContainer.ElementList res = null;
        if(signature != null) {
            con.addElement(data);
            con.addElement(signature);
            con.addElement(meta);
            say("Verifying signature with key: %s%n",meta);
            try {
                res = execute(con.encode(),"VERIFY");
            } catch (CCAException e) {
                say("VERIFY function failed with: %s%n",sayCCAException(e));
            }
        }
        else {
                  say("Please sign text first!%n");
        }
        return res;
    }

    private String[] getUseValues() {
        String valid = getProp("use.values");
        if (!valid.isEmpty()) {
            return valid.split(",");
        }
        return new String[]{};
    }

    private boolean checkUseValue(String use) {
        String[] valid = getUseValues();
        if (valid.length>0) {
            return CCAUtil.inList(use, false, valid);
        }
        return false;
    }
	
    private void processCommand(String[] args) /*throws CCAException*/ {
    	
        String cmd = args.length>0 ? args[0].toUpperCase() : "";
        String opt = args.length>1 ? args[1].toUpperCase() : "";
    	
        if (cmd.startsWith("C")) {
    	    checkKeys();        		
        } else

        if (cmd.startsWith("G") && args.length>1) {
            String useVal = args[1];
            if (checkUseValue(useVal)) {
                TLVContainer con = new TLVContainer();
                con.addElement( useVal);
                try {
                    execute(con.encode(),"GENKEY");
                    say("%s key has been generated%n", useVal);
                } catch (CCAException e) {
                    say("GENKEY function failed with: %s%n",sayCCAException(e));
                }
            }
            else {
                say("Invalid use value(%s) %n",useVal);
            }
        } else
    		
        if (cmd.startsWith("D") &&  args.length>1) {
            String useVal = args[1];
            if (checkUseValue(useVal)) {
                TLVContainer con = new TLVContainer();
                con.addElement( useVal);
                try {
                    execute(con.encode(),"DELKEY");
                } catch (CCAException e) {
                    say("DELKEY function failed with: %s%n",sayCCAException(e));
                }
            }
            else {
                say("Invalid use value(%s) %n",useVal);
            }
        } else

        if (cmd.startsWith("U") &&  args.length>1) {
            String useVal = args[1];
            if (checkUseValue(useVal)) {
                TLVContainer con = new TLVContainer();
                con.addElement(useVal);
                try {
                    execute(con.encode(),"USEKEY");
                    say("Using %s encryption%n", useVal);
                } catch (CCAException e) {
                    say("USEKEY function failed with: %s%n",sayCCAException(e));
                }
            }
            else {
                say("Invalid use value(%s) %n",useVal);
            }
        } else

        if (cmd.startsWith("P")) {
            if (opt.startsWith("C") && args.length>3) {
                copyProp(args[2],args[3]);
            } else
            if (opt.startsWith("L")) {
                listProperties();        		
            } else
            if (opt.startsWith("G") && args.length>2) {
                getProp(args[2]);
            } else
            if (opt.startsWith("S") && args.length>3) {
                setProp(args[2], args[3]);
            } else
            if (opt.startsWith("D") && args.length>2) {
                setProp(args[2], "");
            } else
            if (opt.startsWith("I")) {
                try {
                    execute(null,"SETUP");
                } catch (CCAException e) {
                    say("SETUP function failed with: %s%n",sayCCAException(e));
                }
            }
            else {
                say("property option %s is invalid - use copy init, list, get, set or del%n",opt);
            }
        } else
        if (cmd.startsWith("S")) {
            signtext = CCAUtil.S2B(readData());
            sign(signtext);
        } else
        if (cmd.startsWith("V")) {
            verify(with, signtext, signature);
        }
        else {
            say("Commands are:%n"
                +"  del <use ref>         - delete generated key%n"
                +"  use <use ref>         - set use key for sign/verify%n"
                +"  gen <use ref>         - generate/store key for use value%n"
                +"  check                 - check and list keys for use values%n"
                +"  prop copy <from> <to> - copy use set <from> <to>%n"
                +"  prop init             - initiate properties with defaults%n"
                +"  prop list             - list all properties%n"
                +"  prop del <name>       - delete single property%n"
                +"  prop get <name>       - get single property%n"
                +"  prop set <name> <val> - set property value%n"
                +"  sign                  - sign with current key (call before verify)%n"
                +"  ver                   - verify signature with current key%n"
                +"  x,q                   - exit%n"
            );
        }
    }

    public void interact() {
        say("Starting Agile Client -%n%n" + TargetInfo.info() + "%n%n");
        String[] args = readCommand();
        do {
            processCommand(args);
            args = readCommand();
       	
        } while (args.length>0 && !CCAUtil.inList(args[0],false,"x","q"));
            say("Terminating Agile client.%n");
    }
    
    private String[] readCommand() {
        String[] cmds;
        int lslen = System.getProperty("line.separator").length();
        say("Enter Agile command or type 'help' for command list: %n");
        try {
            byte[] ab = new byte[132];
            int br = System.in.read(ab);

            if (br<0 || ab.length==0) {
                cmds = new String[0];
            } 
            else {
                ab = CCAUtil.copy(ab, 0, br-lslen);
                cmds = CCAUtil.B2S(ab).split(" ");
            }
        }
        catch (IOException ioe) {
            cmds = new String[0];
        }
        return cmds;
    }
    
    private String readData() {
        say("Enter text to sign: ");

        String text = "";

        int lslen = System.getProperty("line.separator").length();

        try {
            byte[] ab = new byte[132];
            int br = System.in.read(ab);

            ab = CCAUtil.copy(ab, 0, br - lslen);
            text = CCAUtil.B2S(ab);

        } catch(IOException ioe) {
            say("Could not read text, will use '%s'", CCAUtil.B2S(signtext));
        }

        return text;
    }
    
    private String sayCCAException(CCAException e) {
        if (e.isRR(32, 1831)) {
            return "The key already exist";
        } else
        if (e.isRR(32, 1833)) {
            return "Invalid use value";
        } else
        if (e.isRR(32, 1834)) {
            return "Invalid gen parms";
        } else
        if (e.isRR(32, 1835)) {
            return "use value already exist";
        }
        return e.toString();	
    }
    
	/**
	 * Connects to and communicates with any peer using any protocol. Accepts input from stream, sends it to peer and
	 * displays all received responses on console.
	 * @param args command args
	 */
    public static void main(String[] args) {
    if (args.length>0 && args[0].equalsIgnoreCase("server")) {
			ivUdfClass = UDFCLASS_SERVER;
			say("UDF will be executed remotely%n");
	  }
    else {
        // Enable local execution
        CCACommon.setUdfExecutor(new UdfCallExecutor());
        ivUdfClass = UDFCLASS_LOCAL;
	      say("UDF will be executed locally%n");
    }
    new AgileClient().interact();
    }
}

AgileUDF Sample Description

The AgileUDF class demonstrates the use of the UDF properties. The AgileUDF sample program is the server code of the UDF. It implements the following rules, which can be called from the client side:

• CHECK: return PKA keys referenced by the use values
• SETUP: initialize sample properties
• GENKEY: given a use value generate a PKA key to sign and verify data
• USEKEY: switch use value to the one provided
• DELKEY: given use value delete the associated PKA key
• SIGN: given the use value and data, generate a digital signature
• VERIFY: given the use value, data and the signature, verify the signature on the data
• COPYPROP: copy property set of a use value to a new one
• GETPROP: return value of a specific property
• SETPROP: set a new value for specific property
• LISTPROP: return all the properties

The UDF defines a set of private constants for user-defined reason codes to be returned within CCAExceptions for handling unwanted cases related to the UDF properties.

The execute method decodes the TLVContainer with incoming parameters from the client side into an ElementList and passes it to some of the UDF rule handling functions where these parameters are necessary.

The AgileUDF has the following methods:

• execute():

This is the driver method of the UDF, which executes the UDF server code when called from the client side by the UDFCALL pseudo-verb. In AgileUDF the rules are analyzed and calls to other methods are performed, otherwise a CCAException is thrown to indicate invalid rules.

• setupProperties():

This method is called when rule "SETUP" is passed. It initializes the sample UDF properties including the use value and the use values options available with rules and parameters for PKA key generation, hashing, signing and verification.

• useKey():

This method is called when rule "USEKEY" is passed. It checks if the use value passed is in the list of available options and updates the relevant property.

• checkKeys():

This method is called when rule "CHECK" is passed. For each use value option it retrieves a PKA key label stored in the associated property and checks if the PKA key itself is present using the keyExistPKA method from the jCCA KeyUtil class.

• genKEY():

This method is called when rule "GENKEY" is passed. For a given use value it generates a PKA key based on the relevant rules and parameters and store it in the PKA storage.

• deleteKey():

This method is called when rule "DELKEY" is passed. For a given use value it retrieves the PKA key label and calls the deletePKA method from the jCCA KeyUtil class to delete the associated PKA key inside the PKA storage.

• sign():

This method is called when rule "SIGN" is passed. It generates a signature from data and a key label referenced by the given use value. If use value is not provided, it retrieves one from the related UDF property.

• verify():

This method is called when rule "VERIFY" is passed. It verifies a signature on the associated data and key label referenced by the given use value. If the use value is not provided, it retrieves one from the related UDF property.

• listProperties():

This method is called when rule "LISTPROP" is passed. It retrieves all the UDF properties and encodes them in the output TLVContainer.

• getProperty():

This method is called when rule "GETPROP" is passed. For a given UDF property key it returns its value.

• setProperty():

This method is called when rule "SETPROP" is passed. For a given UDF property key it updates its value the one provided. Upon completion it saves the UDF property file to persist the changes.

• copyProperty():

This method is called when rule "COPYPROP" is passed. It copies the whole UDF property set associated with one use value to a new one. It throws CCAException if the source use value does not exist or target use value exists.

A general description of the logic of a UDF server function is:

• Override the execute method of the AUdfFunction framework class to analyze input parameters to control the logic.
• Utility methods from the framework can be called for property management, for example:

• saveProperties();

• getProperties();

• getProperty(String);

• setProperty(String, String);

• Utility functions in the KeyUtil are helpful when executing key handling tasks.
• UDF properties provides additional flexibility in configuring the UDF function. As this configuration is persisted locally, there is no need to send it from the client each time.

AgileUDF Sample Code

package acsp.samples.udf;

import static com.ibm.acsp.client.ConstClient.*;

import com.ibm.acsp.udf.AUdfFunction;
import com.ibm.crypto.hardware.cca.*;
import com.ibm.crypto.hardware.common.CCAException;
import com.ibm.crypto.hardware.common.CCAKeyLabel;
import com.ibm.crypto.hardware.common.CCAUtil;
import com.ibm.crypto.utility.KeyUtil;
import com.ibm.crypto.utility.TLVContainer;

import java.io.IOException;
import java.util.Arrays;
import java.util.Properties;


public class AgileUDF extends AUdfFunction {

    
    private static final String DELIM = ",";

    // Agile UDF
    private static final int ERROR_UDF_AGILE_KEY_EXISTS         = 1831;
    private static final int ERROR_UDF_AGILE_NOT_SAVED            = 1832;
    private static final int ERROR_UDF_AGILE_INVALID_USE_VALUE    = 1833;
    private static final int ERROR_UDF_AGILE_INVALID_GEN_PARMS    = 1834;
    private static final int ERROR_UDF_AGILE_USE_VALUE_EXISTS    = 1835;

    public AgileUDF() {
        // nothing
    }

    @Override
    public void execute() throws CCAException {
        TLVContainer.ElementList args = TLVContainer.decode(getDataIn());

        if (queryRule("CHECK")) {
            checkKeys();
        } else

        if (queryRule("SETUP")) {
            setupProperties();
        } else

        if (queryRule("GENKEY")) {
            genKEY(args);
        } else

        if (queryRule("USEKEY")) {
            useKey(args);
        } else
                
        if (queryRule("DELKEY")) {
            deleteKey(args);
        } else
                
        if (queryRule("SIGN")) {
            sign(args);
        } else 

        if (queryRule("VERIFY")) {
            verify(args);
        } else 
        
        if (queryRule("COPYPROP")) {
            copyProperty(args);
        } else 
            
        if (queryRule("GETPROP")) {
            getProperty(args);
        } else 
            
        if (queryRule("SETPROP")) {
            setProperty(args);
        } else 
            
        if (queryRule("LISTPROP")) {
            listProperties();
        } 
        
        else {
            throw new CCAException(8, 33);    // CCA invalid rule
        }
    }
    private void useKey(TLVContainer.ElementList args) {
        String use = args.getString(0);
        if (checkUseValue(use)) {
            try {
                setProperty("use", use);
                saveProperties();
            } catch (IOException e) {
                logError("Properties not saved - reason: %s", e);
            }
        }                
    }
    
    private void deleteKey(TLVContainer.ElementList args) {
        String use = args.getString(0);
        if (checkUseValue(use)) {
            String keylabel = getProperty(use + ".key","");
            if (KeyUtil.keyExistPKA(keylabel)) {
                logInfo("DELKEY: Key label %s %s", keylabel,KeyUtil.deletePKA(keylabel) ? "deleted":"NOT deleted");
            }
            else {
                logError("DELKEY: Key label %s not found", keylabel);
            }
        }                
    }
    
    private void genKEY(TLVContainer.ElementList args) throws CCAException {
        String use = args.getString(0);

        if (!checkUseValue(use)) {
            logError("GENKEY: Use value(%s) not defined in property use.values'", use);
            throw new CCAException(ACSP_RETURNCODE, ERROR_UDF_AGILE_INVALID_USE_VALUE);
        }
 
        String[] parms = getKeyParms(use);
        if (parms.length<3) {
            logError("GENKEY: Property value '%s.gen.parms' not defined or incomplete", use);
            throw new CCAException(ACSP_RETURNCODE, ERROR_UDF_AGILE_INVALID_GEN_PARMS);
        }
        String gentype = parms[0].toUpperCase();
        int genval1 = Integer.parseInt(parms[1]);
        int genval2 = Integer.parseInt(parms[2]);
         
        String keylabel = getProperty(use +".key","");
        String[] rules = getPropertyRules(use + ".gen.rules");

        if (KeyUtil.keyExistPKA(keylabel)) {
            logError("GENKEY: %s key already exist - Use function DEL %s to delete",keylabel,use);
            throw new CCAException(ACSP_RETURNCODE, ERROR_UDF_AGILE_KEY_EXISTS);
        }

        logInfo("GENKEY: Generating '%s' key",use);

        // build skeleton token
        CSNDPKB pkb = new CSNDPKB();
        pkb.addRules(rules);
        if (gentype.startsWith("E") ) {
            pkb.createECCKeyValueStructure(genval1, genval2);
            String name = genval1==0 ? "Prime" : 
                          genval1==1 ? "BrainPool" : 
                                       "Edwards"; 
            logDebug("GENKEY: ECC key structure skeleton used, curve=%s(%s), bits=%s",genval1, name, genval2);
        } else
        if (gentype.startsWith("R") ) {
            pkb.createRSAKeyValueStructure(genval1, genval2);
            logDebug("GENKEY: RSA key structure skeleton used, modulus=%s, exponent=%s",genval1, genval2);
        } else
        if (gentype.startsWith("Q") ) {
            pkb.createQSAKeyValueStructure(genval1, genval2);
            logDebug("GENKEY: QSA key structure skeleton used, algorithm=%s, format=%s",genval1, genval2);
        }
        pkb.execute();
        // generate key pair
        CSNDPKG pkg = new CSNDPKG();
        pkg.addRule(CSNDPKG.MASTER);
        pkg.setSkeletonKey(pkb.getKeyToken());
        pkg.execute();
        logDebug("GENKEY: %s key generated",gentype);
        // store key pair in pka storage
        CSNDKRC krc = new CSNDKRC();
        krc.setKeyToken(pkg.getGeneratedKeyToken());
        krc.setKeyLabel(CCAKeyLabel.valueOf(keylabel));
        krc.execute();
        logDebug("GENKEY: %s key stored with name: %s",gentype, keylabel);

        logInfo("%s key generated",gentype);
    }


    private void sign(TLVContainer.ElementList args) throws CCAException { 
        byte[] data = args.getBytes(0);
        String use = args.getString(1);

        if (use==null) {
            use = getProperty("use");
        }
        if (!checkUseValue(use)) {
            logError("Use value(%s) not defined in property use.values'", use);
            throw new CCAException(ACSP_RETURNCODE, ERROR_UDF_AGILE_INVALID_USE_VALUE);
        }
        
        String keylabel = getProperty(use + ".key","");
        String[] rules = getPropertyRules(use + ".sign.rules");

        logDebug("Create signature using %s with key label %s",use.toUpperCase(), keylabel);

        CSNDDSG dsg = new CSNDDSG();
        dsg.addRules(rules);
        dsg.setPrivateKey(CCAKeyLabel.valueOf(keylabel));
        
        if (queryRule("MESSAGE")) {
            dsg.setData(data);
        } else {
            byte[] hash = hash(data, getPropertyRules(use + ".hash.rules"));
            dsg.setData(hash);
        }
        dsg.execute();
        logInfo("Created signature using %s with key label %s",use.toUpperCase(), keylabel);
            
        // pack signature with meta data
        TLVContainer outArgs = new TLVContainer();
        outArgs.addElement(dsg.getSignature());
        outArgs.addElement(use);
        // set output
        setDataOut(outArgs.encode());
    }

    private void verify(TLVContainer.ElementList args) throws CCAException { 
        byte[] data = args.getBytes(0);
        byte[] signature = args.getBytes(1);
        String use = args.getString(2);

        if (use==null) {
            use = getProperty("use");
        }

        if (!checkUseValue(use)) {
            logError("Verify: Use value(%s) not defined in property use.values'", use);
            throw new CCAException(ACSP_RETURNCODE, ERROR_UDF_AGILE_INVALID_USE_VALUE);
        }

        
        String keylabel = getProperty(use + ".key","");
        String[] rules = getPropertyRules(use + ".verify.rules");

        logInfo("Verifying signature using %s with key label %s",use.toUpperCase(), keylabel);

        CSNDDSV dsv = new CSNDDSV();
        dsv.addRules(rules);
        dsv.setPublicKey(CCAKeyLabel.valueOf(keylabel));
        dsv.setSignature(signature);

        if (queryRule("MESSAGE")) {
            dsv.setData(data);
        } else {
            byte[] hash = hash(data, getPropertyRules(use + ".hash.rules"));
            dsv.setData(hash);
        }
        dsv.execute();
        logInfo("Verifying signature using %s with key label %s",use.toUpperCase(), keylabel);
    }
    
    private byte[] hash(byte[] text, String... rules) throws CCAException {
        CSNBOWH bowh = new CSNBOWH();

        bowh.addRules(rules);
        bowh.setText(text);
        bowh.execute();
        return bowh.getHash();
    }
    
    private String[] getPropertyRules(String key) {
        String rules = getProperty(key);
        rules = rules == null ? "" : rules;
        String[] res = rules.toUpperCase().split(DELIM);
        logInfo("rules = %s", Arrays.asList(res));
        return res;
    }

    private String[] getUseValues() {
        String valid = getProperty("use.values");
        if (valid!=null) {
            String[] args = valid.split(",");
            for (int i=0;i<args.length;i++) {
                args[i] = args[i].trim(); 
            }
            logDebug("use values = %s", Arrays.asList(args));
            return args;
        }
        logError("use values = NONE!!!");
        return new String[]{};
    }

    private String[] getKeyParms(String use) {
        String valid = getProperty(use + ".gen.parms");
        if (valid!=null) {
            String[] args = valid.split(",");
            if (args.length>2) {
                for (int i=0;i<args.length;i++) {
                    args[i] = args[i].trim(); 
                }
                return args;
            }
            logError("property '%s.gen.parms' too short",use);

        } else {
            logError("property '%s.gen.parms' not found",use);
        }
        return new String[]{};
    }

    private boolean checkUseValue(String use) {
        String[] valid = getUseValues();
        if (valid.length>0) {
            return CCAUtil.inList(use, false, valid);
        }
        return false;
    }

    private void setupProperties() throws CCAException {
        
        logInfo("Initializing sample properties");
        
        setProperty("use","rsa");
        setProperty("use.values","dsa,rsa,qsa");

        setProperty("dsa.key","ACSP.AGILEUDF.DSA");
        setProperty("dsa.gen.rules","ECC-PAIR,SIG-ONLY");
        setProperty("dsa.gen.parms","ecc,1,256");
        setProperty("dsa.sign.rules","ECDSA,MESSAGE,SHA-256");
        setProperty("dsa.verify.rules","ECDSA,MESSAGE,SHA-256");
        setProperty("dsa.hash.rules","SHA-256");

        setProperty("rsa.key","ACSP.AGILEUDF.RSA");
        setProperty("rsa.gen.rules","RSA-AESM,SIG-ONLY");
        setProperty("rsa.gen.parms","rsa,2048,65537");
        setProperty("rsa.sign.rules","PKCS-1.1");
        setProperty("rsa.verify.rules","PKCS-1.1");
        setProperty("rsa.hash.rules","SHA-256");

        setProperty("qsa.key","ACSP.AGILEUDF.QSA");
        setProperty("qsa.gen.rules","QSA-PAIR,U-DIGSIG");
        setProperty("qsa.gen.parms","qsa,1,2");
        setProperty("qsa.sign.rules","CRDL-DSA,MESSAGE,CRDLHASH");
        setProperty("qsa.verify.rules","CRDL-DSA,MESSAGE,CRDLHASH");
        setProperty("qsa.hash.rules","SHA-256");

        saveUDFProperties();
    }

    private void copyProperty(TLVContainer.ElementList args) throws CCAException {
        String from = args.getString(0);
        if (!checkUseValue(from)) {
            logError("from use value '%s' is invalid",from);
            throw new CCAException(32, ERROR_UDF_AGILE_INVALID_USE_VALUE);
        }
        String to = args.getString(1);
        if (checkUseValue(to)) {
            logError("to use value '%s' is already defined",to);
            throw new CCAException(32, ERROR_UDF_AGILE_USE_VALUE_EXISTS);
        }
        logInfo("copying all properties(6) from stanca=%s.* to new stanca=%s.*",from,to);

        setProperty(to + ".key"          ,getProperty(from + ".key",""));
        setProperty(to + ".gen.rules"    ,getProperty(from + ".gen.rules",""));
        setProperty(to + ".gen.parms"    ,getProperty(from + ".gen.parms",""));
        setProperty(to + ".sign.rules"   ,getProperty(from + ".sign.rules",""));
        setProperty(to + ".verify.rules" ,getProperty(from + ".verify.rules",""));
        setProperty(to + ".hash.rules"   ,getProperty(from + ".hash.rules",""));
        
        saveUDFProperties();
    }

    private void getProperty(TLVContainer.ElementList args) {
        String key = args.getString(0);
        String value = getProperty(key);
        logInfo("geting property key(%s) - value(%s)",key,value);
        
        TLVContainer outArgs = new TLVContainer();
        outArgs.addElement(value);
        setDataOut(outArgs.encode());
    }
    
    private void setProperty(TLVContainer.ElementList args) throws CCAException {
        String key = args.getString(0);
        String value = args.getString(1);
        String ovalue = getProperty(key);
        
        if (value.isEmpty()) {
            getProperties().remove(key);
            logInfo("remove property key(%s)",key);
        } else {
            logInfo("Setting property key(%s) to value(%s) - old value(%s)",key,value,ovalue);
            setProperty(key, value);
        }
        
        saveUDFProperties();
    }

    private void listProperties() {
        
        Properties prop = getProperties();
        // pack signature with meta data
        TLVContainer outArgs = new TLVContainer();
        for (String key :prop.stringPropertyNames()) {
            outArgs.addElement(key + " = " + getProperty(key));
        }
        // set output
        setDataOut(outArgs.encode());
        logInfo("List of property values returned - count(%s)",prop.size());
    }

    private void checkKeys() {
        int count = 0;
        TLVContainer out = new TLVContainer();
        for (String use : getUseValues()) {
            count++;
            String label = getProperty(use + ".key");
            if (label==null || label.isEmpty()) {
                out.addElement("%s.key : property not found.",use);
                continue;

            }
            out.addElement(String.format("%s.key = %s : key %s.",
                    use,label,KeyUtil.keyExistPKA(label) ? "present" : "not found"));
        }
        // set output
        setDataOut(out.encode());
        logInfo("List key referenced by use values - count(%s)",count);
        
    }

    
    private void saveUDFProperties() throws CCAException {
        try {
            saveProperties();
        } catch (IOException e) {
            logError("UDF properties not saved - reason: %s", e);
            throw new CCAException(ACSP_RETURNCODE, ERROR_UDF_AGILE_NOT_SAVED);
        }
    }
    
    /** Copyright IBM Corp. */
    public static String copyright() {return Copyright.IBM_COPYRIGHT;}
}

Description

The jCCA generic UDX verb, (UDXCALL) is used to call a UDX function through the jCCA API. The call to the function is done similarly to other CCA verb calls. All the CCA verbs in the jCCA API call the CCA API through a Java Native Interface, JNI, which is a DLL/so module loaded by the Java Runtime Environment (JRE).

When the UDXCALL verb is called, the jCCA JNI will look for and load a shared object (DLL) module called jccauxcl. The JRE will prefix the library name with lib, and use the suffix .so in the z/OS and Linux environments. A library name called:

libjccauxcl.so

will be loaded.

If the shared object is not found or is not loadable, the UDXCALL verb will return an error:

return_code = 20 reason_code = 20,

This is the jCCA way of signaling that the verb is not available on the current platform.

If the jccauxcl JNI module is found, it is loaded and the function name is checked for validity. The jccauxcl module returns an error using the return_code and reason_code fields if the function name is not found.

If the function name is valid, the data_input_length and data_input fields should be passed to the UDX function called for validation of the input data. Other return/reason codes indicating errors may result from the validation.

The data_output_length and data_output parameters are output fields for the UDX function which are returned as results to the caller.

Call Format

Call format in Java

See “Java jCCA API call and CC ACSP Java Client“ below.

Call format in C

void UDXCALL(
    long          * return_code, 
    long          * reason_code, 
    long          * exit_data_length, 
    unsigned char * exit_data, 
    long          * rule_array_count, 
    unsigned char * rule_array, 
    unsigned char * function, 
    long          * input_data_length, 
    unsigned char * input_data, 
    long          * output_data_length, 
    unsigned char * output_data);

Format

In the table below the parameters are listed with their name, whether input or output, data type and data length or value.

Parameters

In this section the parameters are explained.

return_code reason_code exit_data_length exit_data parameters See “Parameters common to all verbs” in “SC14-7508 z/OS ICSF Application Programmers Guide” or “CCA Basic Services Reference and Guide for the IBM 4770, IBM 4769, IBM 4767, and IBM 4765 PCIe Cryptographic Coprocessors Releases 8.4, 7.5, 7.4, 7.3, 7.2, 5.7, 5.6, 5.5, 5.4, 5.3, 4.4, and 4.2”.

rule_array_count The rule_array_count parameter is a pointer to an integer variable which contains the number of elements in the rule_array variable.

rule_array The rule_array parameter is a pointer to a string variable which contains an array of keywords. The keywords are 8 bytes in length, and must be left-aligned and padded on the right with space characters.

function The function parameter is a pointer to a string variable which contains a function name for the UDX function to be called. The function parameter is 8 bytes in length, and must be left-aligned and padded on the right with space characters.

data_input_lengthThe data_input_length parameter is a pointer to an integer variable which contains the length of the data_input variable.

data_input The data_input parameter is a pointer to a string variable which contains input parameters for the UDX function. The content of the data_input variable is defined by the UDX function.

data_output_length The data_output_length parameter is a pointer to an integer variable which contains the length of the data_output variable. At input this parameter should contain the maximum length of the data output which can be used for the output_data variable. At output this variable contains the length of the actually returned output length in the data_output variable.

data_output The data_output parameter is a pointer to a string variable containing output parameters for the UDX function. The content of the data_output variable is defined by the UDX function.

UDXCALL udx = new UDXCALL();
try {
    udx.addRule("RULE1");
    udx.addRule("RULE2");
    udx.setFunction("SAMPLE");
    udx.setInputData(<byte array>);
    udx.execute();
    byte[] result = udx.gettOutputData();
    }
catch (CCAException ce) {
System.out.println("UDXCALL failed with exception: " + ce);
}

C API Call through CC ACSP client

The UDXCALL verb is implemented in the CC ACSP Java Client through jCCA, which creates similar interfaces in the jCCA API and the CC ACSP Java Client.

The UDXCALL verb is also implemented in the CC ACSP CCA C Client, for generic UDX calls in the CC ACSP C interface.

jccauxcl Sample code

#include <stdlib.h>
#include <string.h>
#include <stdio.h>

#if defined( _WIN32 )
    #include <io.h>
    #define DLLEXPORT __declspec(dllexport)
    #define DLLCALL __stdcall
#else /* UNIX... (aix, linux, zlinux, zos, os400) */
    #include <stdio.h>
    #define DLLEXPORT
    #define DLLCALL
#endif

#if defined(__MVS__)
    #define CCAI int
#else
    #define CCAI long
#endif

// prototypes
static void FUNC1 (
    CCAI          * return_code,
    CCAI          * reason_code,
    CCAI          * rule_array_count,
    char          * rule_array,
    char          * function,
    CCAI          * data_in_length,
    unsigned char * data_in,
    CCAI          * data_out_length,
    unsigned char * data_out
);
static void FUNC2 (
    CCAI          * return_code,
    CCAI          * reason_code,
    CCAI          * rule_array_count,
    char          * rule_array,
    char          * function,
    CCAI          * data_in_length,
    unsigned char * data_in,
    CCAI          * data_out_length,
    unsigned char * data_out
);

// helper functions
void print8(char* name) {
    int n = 0;
    for(;n<8;n++) printf("%c",name[n]);
}

void printRules(char* name,int cnt) {
    int j = 0;
    printf("**debug** Number of rules: %d\n",cnt);
    printf("**debug** Rules: ");
    if (cnt>0) {
        for(j=0;j<cnt;j++) {
            printf("'");print8(name+(j*8));printf("'");
            if (j<cnt-1) printf(",");
        }
    } else {
        printf("None");
    }
    printf("\n");
}

/* -------------------------------------------------------------------------- *
 * Generic UDX Call Function (UDXCALL)                                        *
 * -------------------------------------------------------------------------- */
DLLEXPORT void DLLCALL UDXCALL (
    CCAI          * return_code,
    CCAI          * reason_code,
    CCAI          * exit_data_length,
    unsigned char * exit_data,
    CCAI          * rule_array_count,
    char          * rule_array,
    char          * function,
    CCAI          * data_in_length,
    unsigned char * data_in,
    CCAI          * data_out_length,
    unsigned char * data_out
)
{
    int rcnt = *rule_array_count;

    printRules(rule_array,rcnt);
    printf("**debug** Function: '"); print8(function); printf("'\n");
    printf("**debug** Data input length: %ld\n",*data_in_length);
    printf("**debug** Data output length: %ld\n",*data_out_length);

    if (memcmp(function,"FUNC1",5)==0) {
        FUNC1(return_code,reason_code,
              rule_array_count,rule_array,function,
              data_in_length,data_in,
              data_out_length,data_out);
    } else

    if (memcmp(function,"FUNC2",5)==0) {
        FUNC2(return_code,reason_code,
              rule_array_count,rule_array,function,
              data_in_length,data_in,
              data_out_length,data_out);
    }
    else {
        printf("**debug** Undefined function name: '");
        print8(function);
        printf("'\n");
        *return_code = 20;
        *reason_code = 104;  // function not found
    }
}

/* -------------------------------------------------------------------------- *
 * UDXCALL - Sample function: FUNC1                                           *
 * -------------------------------------------------------------------------- */
static void FUNC1 (
    CCAI          * return_code,
    CCAI          * reason_code,
    CCAI          * rule_array_count,
    char          * rule_array,
    char          * function,
    CCAI          * data_in_length,
    unsigned char * data_in,
    CCAI          * data_out_length,
    unsigned char * data_out
)
{
    printf("**debug** Running sample generic UDX call function: FUNC1\n");
    if (*data_out_length >= 12) {
        memcpy(data_out,"FUNC 1 IS OK",12);
        *data_out_length = 12;
        *return_code = 0;
        *reason_code = 0;
    }
    else {
        *return_code = 8;
        *reason_code = 72;  // output size to small
    }
}

/* -------------------------------------------------------------------------- *
 * UDXCALL - Sample function: FUNC2                                           *
 * -------------------------------------------------------------------------- */
static void FUNC2 (
    CCAI         * return_code,
    CCAI          * reason_code,
    CCAI          * rule_array_count,
    char          * rule_array,
    char          * function,
    CCAI          * data_in_length,
    unsigned char * data_in,
    CCAI          * data_out_length,
    unsigned char * data_out
)
{
    printf("**debug** Running sample generic UDX call function: FUNC2\n");
    if (*data_out_length >= 12) {
        memcpy(data_out,"FUNC 2 IS OK",12);
        *data_out_length = 12;
        *return_code = 0;
        *reason_code = 0;
    }
    else {
        *return_code = 8;
        *reason_code = 72;  // output size to small
    }
}

Sample code can also be found in the installed CC ACSP server subdirectory sample file name jccauxcl.c.