/*
 * x509_ed25519.h -- minimal, targeted DER walkers for Ed25519-signed X.509
 * certificates (RFC 8410). Deliberately NOT a general ASN.1/X.509 parser
 * (Milestone 6 decision, FABRIC-2.md): each function walks exactly as far
 * into the DER structure as its own job needs, nothing more.
 *
 * x509_extract_ed25519_pubkey() only ever reads SubjectPublicKeyInfo --
 * no signature verification, no chain validation, no extension parsing.
 * That's the capsule-PKI use case (Milestone 6): the embedded snakeoil
 * intermediate cert is trusted because it's baked into the trusted build,
 * never re-verified against the offline root CA at boot.
 *
 * x509_verify_signature()/x509_extract_serial() (added 2026-08-28,
 * FABRIC-3.md §F.7/§F.17) are for CERTVERIFY -- a regular user's cert,
 * which unlike the capsule-PKI chain is signed by Zuse's own on-device
 * key and genuinely needs its signature checked at attach time, not just
 * trusted by embedding. Two separate trust roots, two separate reasons
 * to exist in the same small file (shared DER-walking internals only).
 *
 * Freestanding C99, no libc beyond memcmp/memcpy (already provided by
 * src/starkernel/vm/host/shim.c in the kernel build).
 */
#ifndef STARKERNEL_X509_ED25519_H
#define STARKERNEL_X509_ED25519_H

#include <stdint.h>
#include <stddef.h>

/* Returns 0 on success (pubkey_out[32] filled), -1 on any malformed
 * encoding, unexpected structure, or non-Ed25519 algorithm. Never
 * faults on malformed input -- every DER length/tag is bounds-checked
 * against der_len before use. */
int x509_extract_ed25519_pubkey(const uint8_t *der, size_t der_len,
                                 uint8_t pubkey_out[32]);

/* Verify a DER-encoded certificate's own outer Ed25519 signature (the
 * signatureValue field) was produced by issuer_pubkey signing the raw,
 * exactly-as-encoded tbsCertificate bytes (DER signs the octets, not a
 * re-derived hash of "the fields" -- the TLV framing is part of what's
 * signed). Rejects a non-Ed25519 signatureAlgorithm rather than guessing.
 *
 * Returns 0 if the signature verifies, -1 on any malformed encoding,
 * unexpected structure, non-Ed25519 signature algorithm, or a signature
 * that does not verify. Never faults on malformed input. */
int x509_verify_signature(const uint8_t *der, size_t der_len,
                           const uint8_t issuer_pubkey[32]);

/* Extract the raw serialNumber INTEGER content bytes from a DER-encoded
 * certificate's tbsCertificate. A single leading 0x00 pad byte (DER adds
 * one when the value's high bit would otherwise read as a negative
 * INTEGER) is stripped before copying, so a 16-byte drive_uuid compares
 * byte-for-byte regardless of whether DER happened to pad it.
 *
 * @param serial_out      Caller-provided buffer.
 * @param serial_out_cap  Its size in bytes; returns -1 if the real
 *                        (pad-stripped) serial is larger than this.
 * @param serial_len_out  Set to the real length actually copied.
 * @return 0 on success, -1 on any malformed encoding or unexpected
 *         structure. Never faults on malformed input. */
int x509_extract_serial(const uint8_t *der, size_t der_len,
                         uint8_t *serial_out, size_t serial_out_cap,
                         size_t *serial_len_out);

/*
 * x509_build_user_cert (added 2026-08-28, FABRIC-3.md §F.8/§F.19, MINT):
 * the encode-side counterpart to x509_verify_signature()/x509_extract_*
 * above. Builds a minimal DER-encoded X.509 certificate exercising
 * exactly the fields those functions read -- serialNumber, an Ed25519
 * SubjectPublicKeyInfo, an Ed25519-signed signatureValue -- and nothing
 * else. issuer/validity/subject are each encoded as an empty SEQUENCE
 * (valid, zero-length DER TLVs the decode side only ever skips, never
 * reads the content of); version is omitted entirely (implicit v1,
 * matching the decode side's own optional-version handling). This is
 * deliberately not a general-purpose X.509 builder -- same scope
 * discipline as the decode side's own doc comment above.
 *
 * @param out            Caller-provided output buffer.
 * @param out_cap        Its size in bytes.
 * @param subject_pubkey The new identity's own Ed25519 public key --
 *                       becomes the cert's SubjectPublicKeyInfo.
 * @param serial         16 bytes -- becomes the cert's serialNumber
 *                       (CERTVERIFY/BINDSTEP compare this against
 *                       homeblocks_sig_t.drive_uuid).
 * @param issuer_seed    The signer's own Ed25519 seed (Zuse's
 *                       vm->zuse_cert_seed) -- signs the resulting
 *                       tbsCertificate bytes.
 * @return Number of bytes written to out, or 0 if out_cap was too small.
 */
size_t x509_build_user_cert(uint8_t *out, size_t out_cap,
                             const uint8_t subject_pubkey[32],
                             const uint8_t serial[16],
                             const uint8_t issuer_seed[32]);

#endif /* STARKERNEL_X509_ED25519_H */