Application Programming Interface

The nShield Post-Quantum Software Development Kit (PQSDK) can build and load a CodeSafe SEE machines onto nShield HSMs:

  • Legacy CodeSafe SEE machines for nShield Solo XC HSMs

  • CodeSafe 5 SEE machines for nShield 5s HSMs.

During this process, a Java binary is produced that enables you to interface with the SEE machine.

See Examples for example programs that show how to use the PQSDK API.

Integration

To integrate the PQSDK within your own Java code, please include /opt/nfast/pqsdk/bin/java/pqsdk.jar in your classpath. pqsdk.jar exposes a Java API for you to integrate with. The source files describing the API exist at /opt/nfast/pqsdk/src/pqsdk/source/java.

You should also ensure that the nCipherKM.jar is installed.

HostCommands

The HostCommands class provides you with a Java interface into the SEE machine. You may then use the exposed API to perform key generation, signing, and verification activities.

HostCommands hc = new HostCommands();

Constants

Modifier and Type Name Value

public static final int

algorithm_dilithium_2

1

public static final int

algorithm_dilithium_3

2

public static final int

algorithm_dilithium_4

3

public static final int

algorithm_falcon_512

4

public static final int

algorithm_falcon_1024

5

public static final int

algorithm_sphincs_haraka_128f_robust

6

public static final int

algorithm_sphincs_haraka_128f_simple

7

public static final int

algorithm_sphincs_haraka_128s_robust

8

public static final int

algorithm_sphincs_haraka_128s_simple

9

public static final int

algorithm_sphincs_haraka_192f_robust

10

public static final int

algorithm_sphincs_haraka_192f_robust

11

public static final int

algorithm_sphincs_haraka_192s_robust

12

public static final int

algorithm_sphincs_haraka_192s_simple

13

public static final int

algorithm_sphincs_haraka_256f_robust

14

public static final int

algorithm_sphincs_haraka_256f_simple

15

public static final int

algorithm_sphincs_haraka_256s_robust

16

public static final int

algorithm_sphincs_haraka_256s_simple

17

public static final int

algorithm_sphincs_sha256_128f_robust

18

public static final int

algorithm_sphincs_sha256_128f_simple

19

public static final int

algorithm_sphincs_sha256_128s_robust

20

public static final int

algorithm_sphincs_sha256_128s_simple

21

public static final int

algorithm_sphincs_sha256_192f_robust

22

public static final int

algorithm_sphincs_sha256_192f_simple

23

public static final int

algorithm_sphincs_sha256_192s_robust

24

public static final int

algorithm_sphincs_sha256_192s_simple

25

public static final int

algorithm_sphincs_sha256_256f_robust

26

public static final int

algorithm_sphincs_sha256_256f_simple

27

public static final int

algorithm_sphincs_sha256_256s_robust

28

public static final int

algorithm_sphincs_sha256_256s_simple

29

public static final int

algorithm_sphincs_shake256_128f_robust

30

public static final int

algorithm_sphincs_shake256_128f_simple

31

public static final int

algorithm_sphincs_shake256_128s_robust

32

public static final int

algorithm_sphincs_shake256_128s_simple

33

public static final int

algorithm_sphincs_shake256_192f_robust

34

public static final int

algorithm_sphincs_shake256_192f_simple

35

public static final int

algorithm_sphincs_shake256_192s_robust

36

public static final int

algorithm_sphincs_shake256_192s_simple

37

public static final int

algorithm_sphincs_shake256_256f_robust

38

public static final int

algorithm_sphincs_shake256_256f_simple

39

public static final int

algorithm_sphincs_shake256_256s_robust

40

public static final int

algorithm_sphincs_shake256_256s_simple

41

public static final int

algorithm_dilithium_5

42

public static final int

algorithm_dilithium_2_aes

43

public static final int

algorithm_dilithium_3_aes

44

public static final int

algorithm_dilithium_5_aes

45

public static final int

algorithm_kyber_512

46

public static final int

algorithm_kyber_768

47

public static final int

algorithm_kyber_1024

48

public static final int

algorithm_kyber_512_90s

49

public static final int

algorithm_kyber_768_90s

50

public static final int

algorithm_kyber_1024_90s

51

Methods

init(String)

protected void init (String published)

Initialises the HostCommands object.

Throws

RuntimeException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

algorithm_toString(long)

public static String algorithm_toString(long value)

Gets the name of an algorithm, given a constant value.

Parameters

value - an algorithm id constant.

Returns

A String value describing the algorithm, or UNKNOWN.

getVersion()

public getVersionResponse getVersion()

Gets the version of the SEE machine interface.

Returns

A getVersionResponse object encapsulating the SEE machine version.

Throws

NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

list()

public listResponse list()

List all PQC keys

Returns

A listResponse object encapsulating a list of key hashes.

Throws

NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

  • The nShield HSM ran out of memory.

getPublic(String)

public getPublicResponse getPublic(String alias)

Get the public half of a PQC key-pair

Parameters

alias - the name of the key

Returns

A getPublicResponse object encapsulating the key

Throws

NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

  • The nShield HSM ran out of memory.

  • The key did not exist.

generate(String, int, boolean)

public generateResponse generate(String alias, int algorithm, boolean overwrite)

Generate a key pair

Parameters

alias - the alias under which to store the key pair.
algorithm - the PQC algorithm (one of the algorithms in HostCommands.algorithm_*).
overwrite - if true, and alias exists, overwrites the existing key pair.

Returns

A generateResponse object encapsulating the alias and hash of the generated key pair.

Throws

NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

  • The nShield HSM ran out of memory.

generate(String, int)

public generateResponse generate(String alias, int algorithm)

Generate a key pair

Parameters

alias - the alias under which to store the key pair.
algorithm - the PQC algorithm (one of the algorithms in HostCommands.algorithm_*).

Returns

A generateResponse object encapsulating the alias and hash of the generated key pair.

Throws

NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

  • The nShield HSM ran out of memory.

importKeypair(String, int, byte[], byte[], boolean)

public importKeypairResponse importKeypair(String alias, int algorithm, byte[] publicKey, byte[] privateKey, boolean overwrite)

Import a key pair

Parameters

alias - the alias under which to store the key pair.
algorithm - the PQC algorithm (one of the algorithms in HostCommands.algorithm_*).
publicKey - the public key represented as a byte array.
privateKey - the private key represented as a byte array.
overwrite - if true, and alias exists, overwrites the existing key pair.

Returns

A importKeypairResponse object encapsulating the alias and hash of the imported key pair.

Throws

NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

  • The nShield HSM ran out of memory.

importKeypair(String, int, byte[], byte[])

public importKeypairResponse importKeypair(String alias, int algorithm, byte[] publicKey, byte[] privateKey)

Import a key pair

Parameters

alias - the alias under which to store the key pair.
algorithm - the PQC algorithm (one of the algorithms in HostCommands.algorithm_*).
publicKey - the public key represented as a byte array.
privateKey - the private key represented as a byte array.

Returns

A importKeypairResponse object encapsulating the alias and hash of the imported key pair.

Throws

NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

  • The nShield HSM ran out of memory.

sign(String, byte[], byte[])

public signResponse sign(String alias, byte[] keyhash, byte[] message)

Sign a message

Parameters

alias - (optional) the name of the key with which to sign.
keyhash - the hash of the key with which to sign.
message - the message to sign.

Returns

A signResponse object encapsulating the message signature.

Throws

IOException - if the key could not be read.
NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

sign(String, byte[])

public signResponse sign(String alias, byte[] message)

Sign a message

Parameters

alias - the name of the key with which to sign.
message - the message to sign.

Returns

A signResponse object encapsulating the message signature.

Throws

IOException - if the key could not be read.
NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

sign(byte[], byte[])

public signResponse sign(byte[] keyhash, byte[] message)

Sign a message

Parameters

keyhash - the hash of the key with which to sign.
message - the message to sign.

Returns

A signResponse object encapsulating the message signature.

Throws

IOException - if the key could not be read.
NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

verify(String, byte[], byte[], byte[])

public verifyResponse verify(String alias, byte[] keyhash, byte[] message, byte[] signature)

Verify the signature of message

Parameters

alias - (optional) the name of the key to verify with.
keyhash - the hash of the key to verify with.
message - the message to verify.
signature - the message signature.

Returns

A verifyResponse object encapsulating a boolean value indicating the operation status.

Throws

IOException - if the key could not be read.
NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

verify(String, byte[], byte[])

public verifyResponse verify(String keyhash, byte[] message, byte[] signature)

Verify the signature of message

Parameters

alias - the name of the key to verify with.
message - the message to verify.
signature - the message signature.

Returns

A verifyResponse object encapsulating a boolean value indicating the operation status.

Throws

IOException - if the key could not be read.
NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

verify(byte[], byte[], byte[])

public verifyResponse verify(byte[] keyhash, byte[] message, byte[] signature)

Verify the signature of message

Parameters

keyhash - the hash of the key to verify with.
message - the message to verify.
signature - the message signature.

Returns

A verifyResponse object encapsulating a boolean value indicating the operation status.

Throws

IOException - if the key could not be read.
NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

verifyImmediate(byte[], int, byte[], byte[])

public verifyResponse verifyImmediate(byte[] publicKey, int algorithm, byte[] message, byte[] signature)

Verify the signature of message using immediate values

Parameters

publicKey - the public key to verify with.
algorithm - the signature algorithm.
message - the message to verify.
signature - the message signature.

Returns

A verifyResponse object encapsulating a boolean value indicating the operation status.

Throws

NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

encapsulate(String, byte[])

public encapsulateResponse encapsulate(String alias, byte[] keyhash)

Encapsulate a shared secret using the public half of a key pair

Parameters

alias - the name of the public key to encapsulate with.
keyhash - the hash of the public key to encapsulate with. Only used if the alias is null.

Returns

An encapsulateResponse object encapsulating a shared secret in plaintext and a ciphertext (encapsulation) of this shared secret.

Throws

RuntimeException - if the alias passed in does not belong to an existing key.
NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

encapsulate(String)

public encapsulateResponse encapsulate(String alias)

Encapsulate a shared secret using the public half of a key pair

Parameters

alias - the name of the public key to encapsulate with.

Returns

An encapsulateResponse object encapsulating a shared secret in plaintext and a ciphertext (encapsulation) of this shared secret.

Throws

RuntimeException - if the alias passed in does not belong to an existing key.
NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

encapsulate(byte[])

public encapsulateResponse encapsulate(byte[] keyhash)

Encapsulate a shared secret using the public half of a key pair

Parameters

keyhash - the hash of the public key to encapsulate with.

Returns

An encapsulateResponse object encapsulating a shared secret in plaintext and a ciphertext (encapsulation) of this shared secret.

Throws

RuntimeException - if the alias passed in does not belong to an existing key.
NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

encapsulateImmediate(byte[], int)

public encapsulateImmediateResponse encapsulateImmediate(byte[] publicKey, int algorithm)

Encapsulate a shared secret using a public key

Parameters

publicKey - the public key to encapsulate with.
algorithm - the encapsulation algorithm.

Returns

An encapsulateResponse object encapsulating a shared secret in plaintext and a ciphertext (encapsulation) of this shared secret.

Throws

NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

decapsulate(String, byte[], byte[])

public decapsulateResponse decapsulate(String alias, byte[] keyhash, byte[] ciphertext)

Decapsulate a shared secret using the private half of a key pair

Parameters

alias - the name of the private key to decapsulate with.
keyhash - the hash of the private key to decapsulate with. Only used if the alias is null.
ciphertext - the encapsulated secret to decapsulate.

Returns

A decapsulateResponse object encapsulating the shared secret.

Throws

RuntimeException - if the alias passed in does not belong to an existing key.
NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

decapsulate(String, byte[])

public decapsulateResponse decapsulate(String alias, byte[] ciphertext)

Decapsulate a shared secret using the private half of a key pair

Parameters

alias - the name of the private key to decapsulate with.
ciphertext - the encapsulated secret to decapsulate.

Returns

A decapsulateResponse object encapsulating the shared secret.

Throws

RuntimeException - if the alias passed in does not belong to an existing key.
NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.

decapsulate(byte[], byte[])

public decapsulateResponse decapsulate(byte[] keyhash, byte[] ciphertext)

Decapsulate a shared secret using the private half of a key pair

Parameters

keyhash - the hash of the private key to decapsulate with.
ciphertext - the encapsulated secret to decapsulate.

Returns

A decapsulateResponse object encapsulating the shared secret.

Throws

RuntimeException - if the alias passed in does not belong to an existing key.
NFException - if one of the following conditions is met:

  • The PQSDK SEE machine is not installed, published, or running.

  • The Security World is not usable.