Application programming interfaces

Edit online

View a list of application programming interfaces (APIs) for the functions of the current version of libica. All functions are declared in include/ica_api.h.

Note: The list uses the following short-names for IBM® processors:
z16™
IBM z16
z15®
IBM z15® and IBM z15 Model T02
z14
IBM z14® and IBM z14 Model ZR1
z13®
IBM z13® and IBM z13s®
zBC12
IBM zEnterprise® BC12
zEC12
IBM zEnterprise EC12
Note: From a libica point of view, zEnterprise BC12 and zEnterprise EC12 are equivalent and zEnterprise EC12 is used in Table 1 to denote the minimum required processor.
z114
IBM zEnterprise 114
  • LinuxONE is supported whenever IBM z13 is supported.
  • LinuxONE Emperor II and LinuxONE Rockhopper II are supported whenever IBM z14 is supported.
  • LinuxONE III is supported whenever IBM z15 is supported.
  • LinuxONE Emperor 4 is supported whenever IBM z16 is supported.
Table 1. libica APIs

The table lists the application programming interfaces for the current libica version. The table columns list the function, the API name the key length, the supported machines, the CPACF function and states whether there is a software fallback available.
Function libica API name Key length in bits Minimum required processor Hardware support (CPACF or CEX*S)
General support functions
Open adapter handle ica_open_adapter N/A z114 No
Close adapter handle ica_close_adapter N/A z114 No
Enable/Disable SW fallbacks ica_set_fallback_mode N/A z114 No
Enable/Disable offloading to crypto adapters ica_set_offload_mode N/A z114 No
Enable/Disable counting of cryptographic operations ica_set_stats_mode N/A z114 No
Secure hash operations
Secure hash using the SHA-1 algorithm (deprecated) ica_sha1 N/A z114 Yes
Secure hash using the SHA-224 algorithm ica_sha224 N/A z114 Yes
Secure hash using the SHA-256 algorithm ica_sha256 N/A z114 Yes
Secure hash using the SHA-384 algorithm ica_sha384 N/A z114 Yes
Secure hash using the SHA-512 algorithm ica_sha512 N/A z114 Yes
Secure hash using the SHA-512/224 algorithm ica_sha512_224 N/A z114 Yes
Secure hash using the SHA-512/256 algorithm ica_sha512_256 N/A z114 Yes
Secure hash using the SHA3-224 algorithm ica_sha3_224 N/A z14 Yes
Secure hash using the SHA3-256 algorithm ica_sha3_256 N/A z14 Yes
Secure hash using the SHA3-384 algorithm ica_sha3_384 N/A z14 Yes
Secure hash using the SHA3-512 algorithm ica_sha3_512 N/A z14 Yes
Secure hash using the SHAKE-128 algorithm ica_shake_128 N/A z14 Yes
Secure hash using the SHAKE-256 algorithm ica_shake_256 N/A z14 Yes
Random number generation
Generate a pseudo random number ica_random_number_generate N/A z114 Yes
Generate pseudo random bits NIST compliant - instantiate ica_drbg_instantiate N/A z13 Yes
Generate pseudo random bits NIST compliant - reseed ica_drbg_reseed N/A z13 Yes
Generate pseudo random bits NIST compliant - generate ica_drbg_generate N/A z13 Yes
Generate pseudo random bits NIST compliant - un-instantiate ica_drbg_uninstantiate N/A z13 Yes
Generate pseudo random bits NIST compliant - health test ica_drbg_health_test N/A z13 Yes
Elliptic curve cryptography (ECC) functions
Create an ICA_EC_KEY data structure for a new elliptic curve key ica_ec_key_new N/A z114 Yes, for supported curves
Initialize an ICA_EC_KEY data structure with given values for private and public key ica_ec_key_init N/A z114 Yes, for supported curves
Generate new ECC private and public key values ica_ec_key_generate N/A z114 Yes, for supported curves
Free an ICA_EC_KEY data structure ica_ec_key_free N/A z114 Yes, for supported curves
Calculate the Diffie-Hellman shared secret ica_ecdh_derive_secret N/A z114 Yes, for supported curves
Obtain the public key of an ECC key pair ica_ec_get_public_key N/A z114 Yes, for supported curves
Obtain the private key of an ECC key pair ica_ec_get_private_key N/A z114 Yes, for supported curves
Create an ECDSA signature ica_ecdsa_sign N/A z114 Yes, for supported curves
Create a deterministic ECDSA signature ica_ecdsa_sign_ex N/A z114 Yes, for supported curves
Verify an ECDSA signature ica_ecdsa_verify N/A z114 Yes, for supported curves
Allocate a new context for X25519 keys ica_x25519_ctx_new N/A z15 Yes
Allocate a new context for X448 keys ica_x448_ctx_new N/A z15 Yes
Allocate a new context for Ed25519 keys ica_ed25519_ctx_new N/A z15 Yes
Allocate a new context for Ed448 keys ica_ed448_ctx_new N/A z15 Yes
Copy the private and public X25519 key to the context ica_x25519_key_set 256 z15 Yes
Copy the private and public X448 key to the context ica_x448_key_set 448 z15 Yes
Copy the private and public Ed25519 key to the context ica_ed25519_key_set 256 z15 Yes
Copy the private and public Ed448 key to the context ica_ed448_key_set 448 z15 Yes
Copy the private and public X25519 key from the context ica_x25519_key_get 256 z15 Yes
Copy the private and public X448 key from the context ica_x448_key_get 448 z15 Yes
Copy the private and public Ed25519 key from the context ica_ed25519_key_get 256 z15 Yes
Copy the private and public Ed448 key from the context ica_ed448_key_get 448 z15 Yes
Generate an X25519 key ica_x25519_key_gen 256 z15 Yes
Generate an X448 key ica_x448_key_gen 448 z15z15 Yes
Generate an Ed25519 key ica_ed25519_key_gen 256 z15 Yes
Generate an Ed448 key ica_ed448_key_gen 448 z15 Yes
Derive a shared secret for X25519 keys ica_x25519_derive 256 z15 Yes
Derive a shared secret for X448 keys ica_x448_derive 448 z15 Yes
Sign an Ed25519 key ica_ed25519_sign N/A z15 Yes
Sign an Ed448key ica_ed448_sign N/A z15 Yes
Verify Ed25519 keys ica_ed25519_verify N/A z15 Yes
Verify Ed448 keys ica_ed448_verify N/A z15 Yes
Delete a context for an X25519 key ica_x25519_ctx_del N/A z15 Yes
Delete a context for an X448 key ica_x448_ctx_del N/A z15 Yes
Delete a context for an Ed25519 key ica_ed25519_ctx_del N/A z15 Yes
Delete a context for an Ed448 key ica_ed448_ctx_del N/A z15 Yes
RSA key generation functions
Generate RSA keys in modulus/exponent format ica_rsa_key_generate_mod_expo N/A z114 No
Generate RSA keys in CRT format ica_rsa_key_generate_crt N/A z114 No
RSA encryption and decryption operations
RSA encryption and decryption operation using a key in modulus/exponent format ica_rsa_mod_expo Depends on supp. key size of Crypto Express feature z114 No
RSA encryption and decryption operation using a key in Chinese-Remainder Theorem (CRT) format ica_rsa_crt Depends on supp. key size of Crypto Express feature z114

CEX*S: Yes
CPACF: No
AES functions
AES with Cipher Block Chaining mode ica_aes_cbc 128, 192, 256 z114 Yes
AES with CBC-Cipher text stealing mode ica_aes_cbc_cs 128, 192, 256 z114 Yes
AES with Counter with Cipher Block Chaining - Message Authentication Code mode ica_aes_ccm 128, 192, 256 zEC12 Yes
AES with Cipher Feedback mode ica_aes_cfb 128, 192, 256 z114 Yes
AES with CMAC mode ica_aes_cmac 128, 192, 256 zEC12 Yes
AES with CMAC mode process intermediate chunks ica_aes_cmac_intermediate 128, 192, 256 zEC12 Yes
AES with CMAC mode process last chunk ica_aes_cmac_last 128, 192, 256 zEC12 Yes
AES with Counter mode ica_aes_ctr 128, 192, 256 z114 Yes
AES with Counter mode, using a list of counters ica_aes_ctrlist 128, 192, 256 z114 Yes
AES with Electronic Code Book mode ica_aes_ecb 128, 192, 256 z114 Yes
AES with Galois/Counter Mode (GCM) for single operations ica_aes_gcm 128, 192, 256 z114 Yes
AES with Galois/Counter Mode (GCM) for streaming operations - initialize ica_aes_gcm_initialize 128, 192, 256 z114 Yes
AES with Galois/Counter Mode (GCM) for streaming operations - initialize with internally created IV ica_aes_gcm_initialize_fips 128, 192, 256 z114 Yes
AES with Galois/Counter Mode (GCM) for streaming operations - intermediate ica_aes_gcm_intermediate 128, 192, 256 z114 Yes
AES with Galois/Counter Mode (GCM) for streaming operations - last ica_aes_gcm_last 128, 192, 256 z114 Yes
AES with Galois/Counter Mode (GCM) for KMA exploitation - pointer to new GCM context ica_aes_gcm_kma_ctx_new 128, 192, 256 z114 Yes
AES with Galois/Counter Mode (GCM) for KMA exploitation - deallocate new GCM context ica_aes_gcm_kma_ctx_free 128, 192, 256 z114 Yes
AES with Galois/Counter Mode (GCM) for KMA exploitation - initialize new GCM context ica_aes_gcm_kma_init 128, 192, 256 z114 Yes
AES with Galois/Counter Mode (GCM) for KMA exploitation - initialize new GCM context in FIPS mode ica_aes_gcm_kma_init_fips 128, 192, 256 z114 Yes
AES with Galois/Counter Mode (GCM) for KMA exploitation - perform encryption or decryption with authentication ica_aes_gcm_kma_update 128, 192, 256 z114 Yes
AES with Galois/Counter Mode (GCM) for KMA exploitation - get authentication tag ica_aes_gcm_kma_get_tag 128, 192, 256 z114 Yes
AES with Galois/Counter Mode (GCM) for KMA exploitation - verify authentication tag ica_aes_gcm_kma_verify_tag 128, 192, 256 z114 Yes
AES with Output Feedback mode ica_aes_ofb 128, 192, 256 zEC12 Yes
AES with XEX-based Tweaked Code Book mode (TCB) with CipherText Stealing (CTS) - single-part operation ica_aes_xts 128, 256 zEC12 Yes
AES with XEX-based Tweaked Code Book mode (TCB) with CipherText Stealing (CTS) - multi-part operation ica_aes_xts_ex 128, 256 zEC12 Yes
TDES/3DES functions
TDES with Cipher Block Chaining mode ica_3des_cbc 168 z114 Yes
TDES with CBC-Cipher text Stealing mode ica_3des_cbc_cs 168 z114 Yes
TDES with Cipher Feedback mode ica_3des_cfb 168 z114 Yes
TDES with CMAC mode ica_3des_cmac 168 zEC12 Yes
TDES with CMAC mode process intermediate chunks ica_3des_cmac_intermediate 168 zEC12 Yes
TDES with CMAC mode process last chunk ica_3des_cmac_last 168 zEC12 Yes
TDES with Counter mode ica_3des_ctr 168 z114 Yes
TDES with Counter mode, using a list of counters ica_3des_ctrlist 168 z114 Yes
TDES with Electronic Code Book mode ica_3des_ecb 168 z114 Yes
TDES with Output Feedback mode ica_3des_ofb 168 zEC12 Yes
Information retrieval functions
Return version information for libica ica_get_version N/A z114 N/A
Return libica build information ica_get_build_version N/A z114 N/A
Return hardware information about the used processor ica_get_hw_info N/A z114 N/A
Return the processor's highest message security assist level (MSA Extension) ica_get_msa_level N/A z114 N/A
Return a list of cryptographic mechanisms supported by libica ica_get_functionlist N/A z114 N/A
FIPS mode functions
Queries and reruns a FIPS status and whether libica is running in FIPS mode ica_fips_status N/A z114 N/A
Triggers the implemented self-tests when running in FIPS mode ica_fips_powerup_tests N/A z114 N/A
Returns FIPS compliance indication for each hardware function or any other mechanism ica_get_fips_indicator N/A z114 N/A
Allow external GCM initialization vector when running in FIPS mode ica_allow_external_gcm_iv_in_fips_mode N/A z14 N/A
SIMD support
Multiply two 512-bit numbers ica_mp_mul512 N/A z14 Yes
Square a 512-bit number ica_mp_sqr512 N/A z14 Yes
DES functions (deprecated)
DES with Cipher Block Chaining mode ica_des_cbc 56 z114 Yes
DES with CBC-Cipher text stealing mode ica_des_cbc_cs 56 z114 Yes
DES with Cipher Feedback mode ica_des_cfb 56 z114 No
DES with CMAC mode ica_des_cmac 56 zEC12 Yes
DES with CMAC mode process intermediate chunks ica_des_cmac_intermediate 56 zEC12 Yes
DES with CMAC mode process last chunk ica_des_cmac_last 56 zEC12 Yes
DES with Counter mode ica_des_ctr 56 z114 Yes
DES with Counter mode, using a list of counters ica_des_ctrlist 56 z114 Yes
DES with Electronic Code Book mode ica_des_ecb 56 z114 Yes
DES with Output Feedback mode ica_des_ofb 56 zEC12 Yes
Note: If you are using the libica-cex.so module, but try to invoke a function that is not supported by the libica-cex library, then the function issues the following return code:
EPERM
Operation not permitted by hardware or software restrictions.