|
SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
|
Platform-specific finite-field, EC-KCDSA, DSA, SHAKE256 and SM4 operations.
These APIs require Nordic CRACEN libraries and initialized PSA Crypto. See SharkSSL Nordic CRACEN integration for source selection and platform requirements. They do not add TLS cipher suites or signature schemes.
Files | |
| file | SharkSslCRACENFF.h |
| See SharkSSL Nordic CRACEN integration for required sources and platform setup. | |
| file | SharkSslCRACENECKCDSA.h |
| See SharkSSL Nordic CRACEN integration for required sources and platform setup. | |
| file | SharkSslCRACENDSA.h |
| See SharkSSL Nordic CRACEN integration for required sources and platform setup. | |
| file | SharkSslCRACENSHAKE256.h |
| See SharkSSL Nordic CRACEN integration for required sources and platform setup. | |
| file | SharkSslCRACENSM4.h |
| See SharkSSL Nordic CRACEN integration for required sources and platform setup. | |
Data Structures | |
| struct | SharkSslCRACENFF |
| Nordic CRACEN finite-field context. More... | |
Macros | |
| #define | SHARKSSL_CRACEN_FF_OK 0 |
| Operation succeeded (0). More... | |
| #define | SHARKSSL_CRACEN_FF_BAD_ARGUMENT -1 |
| Invalid argument or unsupported input size. More... | |
| #define | SHARKSSL_CRACEN_FF_UNAVAILABLE -2 |
| Required hardware or capability unavailable. More... | |
| #define | SHARKSSL_CRACEN_FF_HARDWARE_ERROR -3 |
| Hardware operation failed. More... | |
| #define | SHARKSSL_CRACEN_ECKCDSA_P256_BYTES 32 |
| P-256 scalar and coordinate size in bytes. More... | |
| #define | SHARKSSL_CRACEN_ECKCDSA_OK 0 |
| Operation succeeded (0). More... | |
| #define | SHARKSSL_CRACEN_ECKCDSA_BAD_ARGUMENT -1 |
| Invalid argument or unsupported input size. More... | |
| #define | SHARKSSL_CRACEN_ECKCDSA_INVALID_SIGNATURE -2 |
| Signature or public key rejected. More... | |
| #define | SHARKSSL_CRACEN_ECKCDSA_UNAVAILABLE -3 |
| Required hardware or capability unavailable. More... | |
| #define | SHARKSSL_CRACEN_ECKCDSA_HARDWARE_ERROR -4 |
| Hardware operation failed. More... | |
| #define | SHARKSSL_CRACEN_ECKCDSA_RETRY_NONCE -5 |
| Retry signing with a fresh nonce. More... | |
| #define | SHARKSSL_CRACEN_DSA_P_BYTES 256 |
| DSA domain prime and public key size in bytes. More... | |
| #define | SHARKSSL_CRACEN_DSA_Q_BYTES 32 |
| DSA order, scalar, digest and signature component size in bytes. More... | |
| #define | SHARKSSL_CRACEN_DSA_OK 0 |
| Operation succeeded (0). More... | |
| #define | SHARKSSL_CRACEN_DSA_BAD_ARGUMENT -1 |
| Invalid argument or unsupported input size. More... | |
| #define | SHARKSSL_CRACEN_DSA_INVALID_SIGNATURE -2 |
| Signature or public key rejected. More... | |
| #define | SHARKSSL_CRACEN_DSA_UNAVAILABLE -3 |
| Required hardware or capability unavailable. More... | |
| #define | SHARKSSL_CRACEN_DSA_HARDWARE_ERROR -4 |
| Hardware operation failed. More... | |
| #define | SHARKSSL_CRACEN_DSA_RETRY_NONCE -5 |
| Retry signing with a fresh nonce. More... | |
| #define | SHARKSSL_CRACEN_SHAKE256_MAX_OUTPUT 512 |
| Maximum SHAKE256 output length in bytes. More... | |
| #define | SHARKSSL_CRACEN_SHAKE256_OK 0 |
| Operation succeeded (0). More... | |
| #define | SHARKSSL_CRACEN_SHAKE256_BAD_ARGUMENT -1 |
| Invalid argument or unsupported input size. More... | |
| #define | SHARKSSL_CRACEN_SHAKE256_UNAVAILABLE -2 |
| Required hardware or capability unavailable. More... | |
| #define | SHARKSSL_CRACEN_SHAKE256_HARDWARE_ERROR -3 |
| Hardware operation failed. More... | |
| #define | SHARKSSL_CRACEN_SM4_BLOCK_LEN 16 |
| SM4 block size in bytes. More... | |
| #define | SHARKSSL_CRACEN_SM4_KEY_LEN 16 |
| SM4 key size in bytes. More... | |
| #define | SHARKSSL_CRACEN_SM4_MODE_ECB 0 |
| Electronic codebook mode, without padding. More... | |
| #define | SHARKSSL_CRACEN_SM4_MODE_CBC 1 |
| Cipher block chaining mode, without padding. More... | |
| #define | SHARKSSL_CRACEN_SM4_MODE_CTR 2 |
| Counter mode, including partial final blocks. More... | |
| #define | SHARKSSL_CRACEN_SM4_OK 0 |
| Operation succeeded (0). More... | |
| #define | SHARKSSL_CRACEN_SM4_BAD_ARGUMENT -1 |
| Invalid argument or unsupported input size. More... | |
| #define | SHARKSSL_CRACEN_SM4_UNAVAILABLE -2 |
| Required hardware or capability unavailable. More... | |
| #define | SHARKSSL_CRACEN_SM4_HARDWARE_ERROR -3 |
| Hardware operation failed. More... | |
Typedefs | |
| typedef struct SharkSslCRACENFF | SharkSslCRACENFF |
| Nordic CRACEN finite-field context. More... | |
Functions | |
| int | SharkSslCRACENFF_init (SharkSslCRACENFF *o, const uint8_t *prime, uint16_t primeLen) |
| Initialize a caller-owned finite-field context after PSA Crypto initialization. More... | |
| int | SharkSslCRACENFF_modExp (const SharkSslCRACENFF *o, const uint8_t *base, const uint8_t *exponent, uint8_t *result, uint16_t baseLen, uint16_t exponentLen, uint16_t resultLen) |
| Calculate base^exponent modulo the context's prime. More... | |
| int | sharkssl_CRACENECKCDSA_publicKeyP256 (const uint8_t *privateScalar, uint8_t *publicX, uint8_t *publicY) |
| Generate Q = inverse(d) * G for EC-KCDSA on NIST P-256. More... | |
| int | sharkssl_CRACENECKCDSA_signPartP256 (const uint8_t *privateScalar, const uint8_t *nonce, const uint8_t *r, const uint8_t *h, uint8_t *s) |
| Compute the EC-KCDSA component s = d * (k - ((r xor h) mod n)) mod n. More... | |
| int | sharkssl_CRACENECKCDSA_verifyDigestP256 (const uint8_t *publicX, const uint8_t *publicY, const uint8_t *r, const uint8_t *s, const uint8_t *h) |
| Verify a prehashed EC-KCDSA signature on NIST P-256. More... | |
| int | sharkssl_CRACENDSA_signDigest2048_256 (const uint8_t *p, const uint8_t *q, const uint8_t *g, const uint8_t *privateX, const uint8_t *nonceK, const uint8_t *hash, uint8_t *r, uint8_t *s) |
| Sign a SHA-256 digest using trusted DSA 2048/256 domain parameters. More... | |
| int | sharkssl_CRACENDSA_verifyDigest2048_256 (const uint8_t *p, const uint8_t *q, const uint8_t *g, const uint8_t *publicY, const uint8_t *r, const uint8_t *s, const uint8_t *hash) |
| Verify a prehashed DSA 2048/256 signature. More... | |
| int | sharkssl_CRACENSHAKE256_digest (const uint8_t *input, uint8_t *output, size_t inputLen, size_t outputLen) |
| Compute a one-shot SHAKE256 digest using Nordic CRACEN. More... | |
| int | sharkssl_CRACENSM4_crypt (unsigned int mode, unsigned int decrypt, const uint8_t *key, const uint8_t *iv, const uint8_t *input, size_t inputLen, uint8_t *output, size_t outputSize) |
| Encrypt or decrypt using SM4-128 on Nordic CRACEN. More... | |
| #define SHARKSSL_CRACEN_DSA_BAD_ARGUMENT -1 |
Invalid argument or unsupported input size.
| #define SHARKSSL_CRACEN_DSA_HARDWARE_ERROR -4 |
Hardware operation failed.
| #define SHARKSSL_CRACEN_DSA_INVALID_SIGNATURE -2 |
Signature or public key rejected.
| #define SHARKSSL_CRACEN_DSA_OK 0 |
Operation succeeded (0).
| #define SHARKSSL_CRACEN_DSA_P_BYTES 256 |
DSA domain prime and public key size in bytes.
| #define SHARKSSL_CRACEN_DSA_Q_BYTES 32 |
DSA order, scalar, digest and signature component size in bytes.
| #define SHARKSSL_CRACEN_DSA_RETRY_NONCE -5 |
Retry signing with a fresh nonce.
| #define SHARKSSL_CRACEN_DSA_UNAVAILABLE -3 |
Required hardware or capability unavailable.
| #define SHARKSSL_CRACEN_ECKCDSA_BAD_ARGUMENT -1 |
Invalid argument or unsupported input size.
| #define SHARKSSL_CRACEN_ECKCDSA_HARDWARE_ERROR -4 |
Hardware operation failed.
| #define SHARKSSL_CRACEN_ECKCDSA_INVALID_SIGNATURE -2 |
Signature or public key rejected.
| #define SHARKSSL_CRACEN_ECKCDSA_OK 0 |
Operation succeeded (0).
| #define SHARKSSL_CRACEN_ECKCDSA_P256_BYTES 32 |
P-256 scalar and coordinate size in bytes.
| #define SHARKSSL_CRACEN_ECKCDSA_RETRY_NONCE -5 |
Retry signing with a fresh nonce.
| #define SHARKSSL_CRACEN_ECKCDSA_UNAVAILABLE -3 |
Required hardware or capability unavailable.
| #define SHARKSSL_CRACEN_FF_BAD_ARGUMENT -1 |
Invalid argument or unsupported input size.
| #define SHARKSSL_CRACEN_FF_HARDWARE_ERROR -3 |
Hardware operation failed.
| #define SHARKSSL_CRACEN_FF_OK 0 |
Operation succeeded (0).
| #define SHARKSSL_CRACEN_FF_UNAVAILABLE -2 |
Required hardware or capability unavailable.
| #define SHARKSSL_CRACEN_SHAKE256_BAD_ARGUMENT -1 |
Invalid argument or unsupported input size.
| #define SHARKSSL_CRACEN_SHAKE256_HARDWARE_ERROR -3 |
Hardware operation failed.
| #define SHARKSSL_CRACEN_SHAKE256_MAX_OUTPUT 512 |
Maximum SHAKE256 output length in bytes.
| #define SHARKSSL_CRACEN_SHAKE256_OK 0 |
Operation succeeded (0).
| #define SHARKSSL_CRACEN_SHAKE256_UNAVAILABLE -2 |
Required hardware or capability unavailable.
| #define SHARKSSL_CRACEN_SM4_BAD_ARGUMENT -1 |
Invalid argument or unsupported input size.
| #define SHARKSSL_CRACEN_SM4_BLOCK_LEN 16 |
SM4 block size in bytes.
| #define SHARKSSL_CRACEN_SM4_HARDWARE_ERROR -3 |
Hardware operation failed.
| #define SHARKSSL_CRACEN_SM4_KEY_LEN 16 |
SM4 key size in bytes.
| #define SHARKSSL_CRACEN_SM4_MODE_CBC 1 |
Cipher block chaining mode, without padding.
| #define SHARKSSL_CRACEN_SM4_MODE_CTR 2 |
Counter mode, including partial final blocks.
| #define SHARKSSL_CRACEN_SM4_MODE_ECB 0 |
Electronic codebook mode, without padding.
| #define SHARKSSL_CRACEN_SM4_OK 0 |
Operation succeeded (0).
| #define SHARKSSL_CRACEN_SM4_UNAVAILABLE -2 |
Required hardware or capability unavailable.
| typedef struct SharkSslCRACENFF SharkSslCRACENFF |
Nordic CRACEN finite-field context.
The caller owns prime for the lifetime of the context. The caller must initialize PSA Crypto before init. The prime must be a trusted, validated odd prime; init checks only its encoding and hardware size, not primality.
| int sharkssl_CRACENDSA_signDigest2048_256 | ( | const uint8_t * | p, |
| const uint8_t * | q, | ||
| const uint8_t * | g, | ||
| const uint8_t * | privateX, | ||
| const uint8_t * | nonceK, | ||
| const uint8_t * | hash, | ||
| uint8_t * | r, | ||
| uint8_t * | s | ||
| ) |
Sign a SHA-256 digest using trusted DSA 2048/256 domain parameters.
Initialize PSA Crypto first. The caller must validate the domain's primality and order and supply a fresh secret nonce for every signature. All buffers are caller-owned, must not overlap, and hold unsigned big-endian values.
| p | Required 256-byte domain prime. |
| q | Required 32-byte subgroup order. |
| g | Required 256-byte domain generator. |
| privateX | Required 32-byte private scalar, from 1 through q-1. |
| nonceK | Required fresh secret 32-byte nonce, from 1 through q-1. |
| hash | Required 32-byte SHA-256 message digest. |
| r | Required 32-byte output for the first signature component. |
| s | Required 32-byte output for the second signature component. |
| SHARKSSL_CRACEN_DSA_OK | Signature written. |
| SHARKSSL_CRACEN_DSA_BAD_ARGUMENT | NULL pointer or invalid scalar. |
| SHARKSSL_CRACEN_DSA_UNAVAILABLE | Required CRACEN capability unavailable. |
| SHARKSSL_CRACEN_DSA_HARDWARE_ERROR | CRACEN operation failed; r and s cleared. |
| SHARKSSL_CRACEN_DSA_RETRY_NONCE | Outputs cleared; retry with a new nonce. |
| int sharkssl_CRACENDSA_verifyDigest2048_256 | ( | const uint8_t * | p, |
| const uint8_t * | q, | ||
| const uint8_t * | g, | ||
| const uint8_t * | publicY, | ||
| const uint8_t * | r, | ||
| const uint8_t * | s, | ||
| const uint8_t * | hash | ||
| ) |
Verify a prehashed DSA 2048/256 signature.
Initialize PSA Crypto first. The caller supplies trusted domain parameters; this function checks the public key's range and subgroup membership. All inputs are required caller-owned, nonoverlapping big-endian buffers, retained only for this call.
| p | 256-byte domain prime. |
| q | 32-byte subgroup order. |
| g | 256-byte domain generator. |
| publicY | 256-byte public key. |
| r | 32-byte first signature component, from 1 through q-1. |
| s | 32-byte second signature component, from 1 through q-1. |
| hash | 32-byte SHA-256 message digest. |
| SHARKSSL_CRACEN_DSA_OK | Signature verified. |
| SHARKSSL_CRACEN_DSA_BAD_ARGUMENT | Invalid pointer or domain encoding. |
| SHARKSSL_CRACEN_DSA_INVALID_SIGNATURE | Invalid signature or public key. |
| SHARKSSL_CRACEN_DSA_UNAVAILABLE | Required CRACEN capability unavailable. |
| SHARKSSL_CRACEN_DSA_HARDWARE_ERROR | CRACEN operation failed. |
| int sharkssl_CRACENECKCDSA_publicKeyP256 | ( | const uint8_t * | privateScalar, |
| uint8_t * | publicX, | ||
| uint8_t * | publicY | ||
| ) |
Generate Q = inverse(d) * G for EC-KCDSA on NIST P-256.
Initialize PSA Crypto first. All buffers are caller-owned, must not overlap, and contain unsigned 32-byte big-endian integers. Valid output buffers are cleared on hardware failure.
| privateScalar | Required private scalar d in the range 1 through n-1, where n is the P-256 group order. |
| publicX | Required 32-byte output for Q.x. |
| publicY | Required 32-byte output for Q.y. |
| SHARKSSL_CRACEN_ECKCDSA_OK | Public key written. |
| SHARKSSL_CRACEN_ECKCDSA_BAD_ARGUMENT | NULL pointer or invalid scalar. |
| SHARKSSL_CRACEN_ECKCDSA_UNAVAILABLE | Required CRACEN capability unavailable. |
| SHARKSSL_CRACEN_ECKCDSA_HARDWARE_ERROR | CRACEN operation failed. |
| int sharkssl_CRACENECKCDSA_signPartP256 | ( | const uint8_t * | privateScalar, |
| const uint8_t * | nonce, | ||
| const uint8_t * | r, | ||
| const uint8_t * | h, | ||
| uint8_t * | s | ||
| ) |
Compute the EC-KCDSA component s = d * (k - ((r xor h) mod n)) mod n.
Initialize PSA Crypto first. The caller must generate a fresh secret nonce k for each signature and calculate r = SHA-256((k * G).x) and h = SHA-256(z || message). This is not a complete signer. All buffers are caller-owned, must not overlap, and contain 32-byte big-endian values.
| privateScalar | Required private scalar d, from 1 through n-1. |
| nonce | Required fresh secret nonce k, from 1 through n-1. |
| r | Required SHA-256 digest of the nonce point's x coordinate. |
| h | Required precomputed EC-KCDSA message digest. |
| s | Required 32-byte output for the second signature component; cleared on hardware failure or a retry result. |
| SHARKSSL_CRACEN_ECKCDSA_OK | Component s written. |
| SHARKSSL_CRACEN_ECKCDSA_BAD_ARGUMENT | NULL pointer or invalid scalar. |
| SHARKSSL_CRACEN_ECKCDSA_UNAVAILABLE | Required CRACEN capability unavailable. |
| SHARKSSL_CRACEN_ECKCDSA_HARDWARE_ERROR | CRACEN operation failed. |
| SHARKSSL_CRACEN_ECKCDSA_RETRY_NONCE | Generate a new nonce and matching r. |
| int sharkssl_CRACENECKCDSA_verifyDigestP256 | ( | const uint8_t * | publicX, |
| const uint8_t * | publicY, | ||
| const uint8_t * | r, | ||
| const uint8_t * | s, | ||
| const uint8_t * | h | ||
| ) |
Verify a prehashed EC-KCDSA signature on NIST P-256.
Compute W = ((r xor h) mod n) * G + s * Q and check SHA-256(W.x) == r. Initialize PSA Crypto first. All inputs are required caller-owned, nonoverlapping 32-byte big-endian buffers, retained only for this call.
| publicX | Public key Q.x. |
| publicY | Public key Q.y. |
| r | First signature component. |
| s | Second signature component, from 1 through n-1. |
| h | Precomputed digest SHA-256(z || message). |
| SHARKSSL_CRACEN_ECKCDSA_OK | Signature verified. |
| SHARKSSL_CRACEN_ECKCDSA_BAD_ARGUMENT | NULL input pointer. |
| SHARKSSL_CRACEN_ECKCDSA_INVALID_SIGNATURE | Invalid signature or public point. |
| SHARKSSL_CRACEN_ECKCDSA_UNAVAILABLE | Required CRACEN capability unavailable. |
| SHARKSSL_CRACEN_ECKCDSA_HARDWARE_ERROR | CRACEN or digest operation failed. |
| int sharkssl_CRACENSHAKE256_digest | ( | const uint8_t * | input, |
| uint8_t * | output, | ||
| size_t | inputLen, | ||
| size_t | outputLen | ||
| ) |
Compute a one-shot SHAKE256 digest using Nordic CRACEN.
Initialize PSA Crypto first. Buffers are caller-owned and must not overlap. This interface does not provide streaming XOF output or SHAKE128.
| input | Input buffer, readable for inputLen bytes; NULL only if inputLen is 0. |
| output | Required output buffer, writable for outputLen bytes. Cleared if hardware reservation or processing fails after argument validation. |
| inputLen | Input length in bytes, limited by the CRACEN hash driver. |
| outputLen | Requested digest length in bytes, from 1 through SHARKSSL_CRACEN_SHAKE256_MAX_OUTPUT (512). |
| SHARKSSL_CRACEN_SHAKE256_OK | Digest written. |
| SHARKSSL_CRACEN_SHAKE256_BAD_ARGUMENT | Invalid pointer/length or driver size limit. |
| SHARKSSL_CRACEN_SHAKE256_UNAVAILABLE | Hardware reservation failed. |
| SHARKSSL_CRACEN_SHAKE256_HARDWARE_ERROR | Hash operation failed. |
| int sharkssl_CRACENSM4_crypt | ( | unsigned int | mode, |
| unsigned int | decrypt, | ||
| const uint8_t * | key, | ||
| const uint8_t * | iv, | ||
| const uint8_t * | input, | ||
| size_t | inputLen, | ||
| uint8_t * | output, | ||
| size_t | outputSize | ||
| ) |
Encrypt or decrypt using SM4-128 on Nordic CRACEN.
Initialize PSA Crypto first. Buffers are caller-owned. The output must not overlap the input, key or IV. CBC/ECB process complete blocks without padding; CTR accepts a partial final block. This operation does not authenticate data.
| mode | SHARKSSL_CRACEN_SM4_MODE_ECB, SHARKSSL_CRACEN_SM4_MODE_CBC or SHARKSSL_CRACEN_SM4_MODE_CTR. |
| decrypt | 0 to encrypt or 1 to decrypt. |
| key | Required 16-byte key, retained only for this call. |
| iv | NULL for ECB; required 16-byte initialization vector/counter for CBC/CTR. The buffer is not updated and must be chosen for each operation. |
| input | Required input buffer, readable for inputLen bytes. |
| inputLen | Nonzero length in bytes; a multiple of 16 for ECB/CBC. The length rounded up to a block must fit the CRACEN DMA size limit. |
| output | Required output buffer. The first inputLen bytes are cleared if hardware reservation or processing fails after argument validation. |
| outputSize | Output capacity in bytes, at least inputLen. |
| SHARKSSL_CRACEN_SM4_OK | Output written. |
| SHARKSSL_CRACEN_SM4_BAD_ARGUMENT | Invalid mode, direction, pointer, length or buffer overlap. |
| SHARKSSL_CRACEN_SM4_UNAVAILABLE | Hardware reservation failed or SM4 absent. |
| SHARKSSL_CRACEN_SM4_HARDWARE_ERROR | Cipher operation failed. |
| int SharkSslCRACENFF_init | ( | SharkSslCRACENFF * | o, |
| const uint8_t * | prime, | ||
| uint16_t | primeLen | ||
| ) |
Initialize a caller-owned finite-field context after PSA Crypto initialization.
The prime must be trusted and validated by the caller. This function checks its encoding and hardware size, not primality. No allocation is performed. On failure, a non-NULL context is reset to an uninitialized state.
| o | Required context to initialize. |
| prime | Required unsigned big-endian odd prime with no leading zero. Keep this buffer unchanged and alive while the context is used. |
| primeLen | Prime length in bytes, at least 2 and no larger than the CRACEN finite-field operand limit. |
| SHARKSSL_CRACEN_FF_OK | Context initialized. |
| SHARKSSL_CRACEN_FF_BAD_ARGUMENT | NULL pointer or invalid prime encoding. |
| SHARKSSL_CRACEN_FF_UNAVAILABLE | Hardware capability or size unavailable. |
| int SharkSslCRACENFF_modExp | ( | const SharkSslCRACENFF * | o, |
| const uint8_t * | base, | ||
| const uint8_t * | exponent, | ||
| uint8_t * | result, | ||
| uint16_t | baseLen, | ||
| uint16_t | exponentLen, | ||
| uint16_t | resultLen | ||
| ) |
Calculate base^exponent modulo the context's prime.
Initialize PSA Crypto and the context first. All integers are unsigned and big-endian. Input and output buffers must not overlap. This primitive does not validate a DH group or peer public value; the caller must do so.
| o | Required initialized context; its prime buffer remains caller-owned. |
| base | Required base buffer, readable for baseLen bytes. |
| exponent | Required exponent buffer, readable for exponentLen bytes. |
| result | Required caller-owned output; receives exactly o->primeLen bytes on success. Those bytes are cleared on hardware failure. |
| baseLen | Base length in bytes, from 1 through o->primeLen. |
| exponentLen | Exponent length in bytes, from 1 through o->primeLen. |
| resultLen | Output capacity in bytes, at least o->primeLen. |
| SHARKSSL_CRACEN_FF_OK | Result written. |
| SHARKSSL_CRACEN_FF_BAD_ARGUMENT | Invalid context, pointer or length. |
| SHARKSSL_CRACEN_FF_HARDWARE_ERROR | CRACEN operation failed. |