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, orUNKNOWN
.
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 inHostCommands.algorithm_*
).
overwrite
- if true, andalias
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 inHostCommands.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 inHostCommands.algorithm_*
).
publicKey
- the public key represented as a byte array.
privateKey
- the private key represented as a byte array.
overwrite
- if true, andalias
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 inHostCommands.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 thealias
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.
-