Don't return java.security.KeyPair, but some NATS thing

[scottf]

https://github.com/nats-io/nkeys.java/pull/18/changes#r2711848345

If this isn't correct, it may be wrong since the original.

Yes

Also, it may not matter for the purpose of the NKEY.

Yes. nkeys.java returns incorrect value, but everywhere it calls this method, it expects the value, so things cancel out for the nkey.java itself.

After all, it's essentially just a NATS thing, not a general security thing.

java.security.KeyPair is a general security thing, and io.nats.nkey.NKey#getKeyPair is public.

I'm sure I don't understand why this is a problem, but this works

   Ed25519PrivateKeyParameters privateKey = new Ed25519PrivateKeyParameters(nkey.getKeyPair().getPrivate().getEncoded());
   Ed25519Signer signer = new Ed25519Signer();
   signer.init(true, privateKey);
   signer.update(input, 0, input.length);
   return signer.generateSignature();
}

org.bouncycastle.crypto.params.Ed25519PrivateKeyParameters#Ed25519PrivateKeyParameters(byte[]) expects raw seed, as opposed to io.nats.nkey.KeyWrapper which claims to return key in the PKCS#8 format.

---

Possible solutions are:

• don't return java.security.KeyPair, but some NATS thing
• restrict access to io.nats.nkey.NKey#getKeyPair
• prefix returned values to actually be PKCS#8
  • fixing this here, in FIPS provider, would be as simple as returning result of getEncoded instead of getSecret and calling the previous methods where the raw value is needed within the FipsNKeyProvider

Originally posted by @buleuszmatak in #26 (comment)

[scottf]

Claude analysis of the NKey Encoding Format

Question

NKeys makes public and private keys in an encoding that probably is proprietary, meaning we just made it up. io.nats.nkey.KeyWrapper identifies the format as PKCS#8, but that's not the case and causes issues when someone tries to use the KeyWrapper and extensions outside of NATS internal NKey use. NKeyProviderUtils has encoding functions which essentially are the encoding. Can we tell if this is a known encoding and if so what is that encoding?

Answer

This is not a known standard encoding. It's a NATS-proprietary format. Here's what it does:

Wire format: prefix_byte(s) || raw_ed25519_key_bytes || crc16_le

Then the whole thing is Base32-encoded (RFC 4648 alphabet: A-Z, 2-7) with padding stripped.

Specifically:

• Public keys: 1 prefix byte (type: Server/Cluster/Operator/Account/User) + 32 raw key bytes + 2-byte CRC-16 (little-endian XModem)
• Seeds: 2 prefix bytes (with bit-packing to embed both "seed" marker and type) + 32 seed bytes + 2-byte CRC-16

The Base32 alphabet is standard, and the CRC-16 is standard XModem — but the overall structure (typed prefix + raw key + CRC checksum, base32-encoded) is entirely NATS-specific. It bears no resemblance to PKCS#8 (which is ASN.1 DER with algorithm OIDs), X.509/SPKI, PEM, or any other standard key encoding.

For KeyWrapper.getFormat(), the suggestion is to return "NATS-NKey" — it's descriptive, unambiguous, and won't mislead anyone into thinking it's a standard format they can feed into a KeyFactory or KeyStore.

[scottf]

Key wrapper has been changed

abstract class KeyWrapper implements Key {

    @Override
    public String getAlgorithm() {
        return "EdDSA";
    }

    @Override
    public String getFormat() {
        return "NATS-NKey";
    }
}