synta 0.2.1

ASN.1 parser, decoder, and encoder library with DER/BER support and C FFI
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

# Troubleshooting Guide

This file has been reorganised into the Rust API mdbook.

See **[docs/rust/src/troubleshooting.md](rust/src/troubleshooting.md)** for the
full troubleshooting guide covering installation, parsing errors, code generation,
compilation, runtime, and performance issues.

---

## PKCS#11 URI Key Loading Issues

### `OSSL_STORE_open_ex` fails or returns no private key (OpenSSL backend)

**Symptom:** `BackendPrivateKey::from_pkcs11_uri` returns an error such as
`OSSL_STORE_open_ex('pkcs11:…') failed` or `no private key found at PKCS#11 URI`.

**Causes and fixes:**

1. `pkcs11-provider` is not loaded.  Verify that `OPENSSL_CONF` points to an
   `openssl.cnf` that loads the provider:
   ```bash
   export OPENSSL_CONF=/etc/synta/openssl.cnf
   openssl storeutl -noout pkcs11:token=<label>;object=<key>
   ```
   If `openssl storeutl` also fails, the provider is not configured.

2. The `pkcs11-provider` shared object path in `openssl.cnf` is wrong.  Check
   that `/usr/lib64/ossl-modules/pkcs11.so` (or the equivalent path for your
   distribution) exists.

3. The PKCS#11 module path is not set in the provider configuration.  The
   `pkcs11-provider` usually needs to know the path to the underlying PKCS#11
   library (e.g. `libkryoptic_pkcs11.so`).

### `token '…' not found in NSS` (NSS backend)

**Symptom:** `from_pkcs11_uri` returns an error containing `not found in NSS`.

**Cause:** the PKCS#11 module that exposes the token has not been registered in
the NSS secmod database, or the token label does not match the `token=` URI
attribute.

**Fix:** register the module with `modutil` and list tokens to verify the label:
```bash
modutil -dbdir /etc/synta/nssdb -add MyToken -libfile /path/to/pkcs11.so -force
modutil -dbdir /etc/synta/nssdb -list
```
The token label in the URI must match the label shown by `modutil -list` exactly
(case-sensitive).

### `key '…' not found in token` (NSS backend)

**Symptom:** `from_pkcs11_uri` returns an error containing `key … not found in token`.

**Cause:** the `object=` attribute does not match any key nickname in the slot,
or the key does not have the `CKA_SIGN` attribute set.

**Fix:** list the keys present in the slot:
```bash
pkcs11-tool --module /path/to/pkcs11.so     --token-label <label> --login --pin <pin>     --list-objects --type privkey
```
The `Label` field of the object must match the `object=` attribute in the URI.

### `PKCS#11 URI missing 'object' attribute` (NSS backend)

**Symptom:** `from_pkcs11_uri` returns this error at key-load time.

**Cause:** the URI does not include an `object=` path attribute.  The NSS backend
requires both `token=` and `object=` to be present and non-empty.

**Fix:** add the missing attribute to the URI:
```
pkcs11:token=<label>;object=<key-label>;type=private
```

### Ed448 signing fails with `NssUnsupportedSigner` (NSS backend)

**Symptom:** signing with an Ed448 HSM key returns a `PrivateKeyError` at
signing time, even though the key loads successfully.

**Cause:** NSS does not expose `SEC_OID_ED448_SIGNATURE` as a public constant in
releases up to NSS 3.121.  The NSS backend cannot dispatch Ed448 signatures.

**Fix:** use the OpenSSL backend (`--features openssl`) when Ed448 HSM signing
is required.

### `to_pem` / `to_der` returns an empty buffer for an HSM key

**Symptom:** serialising a key loaded via `from_pkcs11_uri` produces an empty
PKCS#8 PEM or DER buffer.

**Cause:** HSM-backed keys store no private-key material in the process.
`pkcs8_der` is always empty for PKCS#11 keys.

**Fix:** do not serialise HSM-backed keys.  Use the key only for signing
(via `as_signer`) or for extracting the public-key SPKI (`public_key_spki_der`).

### `--test-threads=1` required for kryoptic integration tests

**Symptom:** the `pkcs11_kryoptic` integration tests produce spurious failures
or panics when run with the default thread count.

**Cause:** `OPENSSL_CONF` (OpenSSL path) and NSS module state are both
process-global.  Parallel test functions race on this state.

**Fix:** always pass `--test-threads=1` when running PKCS#11 integration tests:
```bash
cargo test -p synta-certificate --test pkcs11_kryoptic --features openssl \
    -- --test-threads=1 --nocapture
```