~~NOTOC~~
{{wvds:title>API Reference}}

===== API Reference =====

All functions are declared in the header ''wvds_crypto.h''.

----

==== Request Builder ====

=== wvds_build_aes_encrypt_request ===

<code c>
int wvds_build_aes_encrypt_request(
    uint8_t* buffer,        // [out] Destination buffer
    size_t* buffer_len,     // [in/out] Buffer size / actual length
    uint32_t key_id,        // Key-ID
    const void* aad,        // Additional Authenticated Data
    size_t aad_len,         // AAD length
    const void* plaintext,  // Data to encrypt
    size_t pt_len           // Plaintext length
);
</code>

| Return | Description |
| 0 | Success |
| -1 | Buffer too small |
| -2 | Payload too large (> 64 KB) |

=== wvds_build_aes_decrypt_request ===

<code c>
int wvds_build_aes_decrypt_request(
    uint8_t* buffer,
    size_t* buffer_len,
    uint32_t key_id,
    const uint8_t nonce[12],
    const uint8_t tag[16],
    const void* aad,
    size_t aad_len,
    const void* ciphertext,
    size_t ct_len
);
</code>

=== wvds_build_mldsa_sign_request ===

<code c>
int wvds_build_mldsa_sign_request(
    uint8_t* buffer,
    size_t* buffer_len,
    uint32_t key_id,        // Private Key ID
    const void* message,
    size_t msg_len
);
</code>

=== wvds_build_mldsa_verify_request ===

<code c>
int wvds_build_mldsa_verify_request(
    uint8_t* buffer,
    size_t* buffer_len,
    uint32_t key_id,        // Public Key ID
    const void* message,
    size_t msg_len,
    const void* signature,
    size_t sig_len
);
</code>

=== wvds_build_mlkem_keygen_request ===

<code c>
int wvds_build_mlkem_keygen_request(
    uint8_t* buffer,
    size_t* buffer_len,
    uint32_t key_id         // ID for new key pair
);
</code>

=== wvds_build_mlkem_encaps_request ===

<code c>
int wvds_build_mlkem_encaps_request(
    uint8_t* buffer,
    size_t* buffer_len,
    const void* public_key,
    size_t pk_len
);
</code>

=== wvds_build_mlkem_decaps_request ===

<code c>
int wvds_build_mlkem_decaps_request(
    uint8_t* buffer,
    size_t* buffer_len,
    uint32_t key_id,        // Private Key ID
    const void* ciphertext,
    size_t ct_len
);
</code>

----

==== Response Parser ====

=== wvds_parse_aes_encrypt_response ===

<code c>
int wvds_parse_aes_encrypt_response(
    const uint8_t* response,
    size_t response_len,
    uint8_t nonce[12],      // [out] Generated nonce
    uint8_t tag[16],        // [out] Authentication Tag
    uint8_t* ciphertext,    // [out] Ciphertext
    size_t* ct_len          // [out] Ciphertext length
);
</code>

| Return | Description |
| 0 | Success |
| >0 | Status Code (see [[.:protokoll#status_codes|Protocol]]) |
| -1 | Response invalid |

=== wvds_parse_aes_decrypt_response ===

<code c>
int wvds_parse_aes_decrypt_response(
    const uint8_t* response,
    size_t response_len,
    uint8_t* plaintext,     // [out] Decrypted plaintext
    size_t* pt_len          // [out] Plaintext length
);
</code>

<WRAP center round alert 60%>
**Return 6 = DECRYPTION_FAILED**

The data was tampered with or wrong key/AAD was used!
</WRAP>

=== wvds_parse_mldsa_sign_response ===

<code c>
int wvds_parse_mldsa_sign_response(
    const uint8_t* response,
    size_t response_len,
    uint8_t* signature,     // [out] Signature (min 4096 bytes)
    size_t* sig_len         // [out] Signature length
);
</code>

=== wvds_parse_mldsa_verify_response ===

<code c>
int wvds_parse_mldsa_verify_response(
    const uint8_t* response,
    size_t response_len,
    int* valid              // [out] 1 = valid, 0 = invalid
);
</code>

=== wvds_parse_mlkem_keygen_response ===

<code c>
int wvds_parse_mlkem_keygen_response(
    const uint8_t* response,
    size_t response_len,
    uint8_t* public_key,    // [out] Public Key (min 2048 bytes)
    size_t* pk_len          // [out] Public Key length
);
</code>

=== wvds_parse_mlkem_encaps_response ===

<code c>
int wvds_parse_mlkem_encaps_response(
    const uint8_t* response,
    size_t response_len,
    uint8_t* ciphertext,    // [out] Ciphertext (min 2048 bytes)
    size_t* ct_len,         // [out] Ciphertext length
    uint8_t shared_secret[32] // [out] Shared Secret
);
</code>

=== wvds_parse_mlkem_decaps_response ===

<code c>
int wvds_parse_mlkem_decaps_response(
    const uint8_t* response,
    size_t response_len,
    uint8_t shared_secret[32] // [out] Shared Secret
);
</code>

----

==== Utility Functions ====

=== wvds_get_error_code ===

<code c>
int wvds_get_error_code(
    const uint8_t* response,
    size_t response_len
);
</code>

Extracts the status code from any response.

| Return | Description |
| 0 | Success |
| 1-9 | Error code (see [[.:protokoll#status_codes|Protocol]]) |
| -1 | Response invalid |

=== wvds_error_to_string ===

<code c>
const char* wvds_error_to_string(int error_code);
</code>

| Code | String |
| 0 | "Success" |
| 1 | "Invalid header" |
| 2 | "Invalid request type" |
| 3 | "Invalid payload" |
| 4 | "Key not found" |
| 5 | "Crypto error" |
| 6 | "Decryption failed" |
| 7 | "Rate limited" |
| 8 | "Nonce reuse detected" |
| 9 | "Payload too large" |

----

==== Constants ====

<code c>
// Request Types
#define WVDS_REQ_AES_ENCRYPT    0x01
#define WVDS_REQ_AES_DECRYPT    0x02
#define WVDS_REQ_MLDSA_SIGN     0x10
#define WVDS_REQ_MLDSA_VERIFY   0x11
#define WVDS_REQ_MLKEM_KEYGEN   0x20
#define WVDS_REQ_MLKEM_ENCAPS   0x21
#define WVDS_REQ_MLKEM_DECAPS   0x22

// Sizes
#define WVDS_AES_NONCE_SIZE     12
#define WVDS_AES_TAG_SIZE       16
#define WVDS_AES_KEY_SIZE       32
#define WVDS_MLDSA65_SIG_SIZE   3293
#define WVDS_MLDSA65_PK_SIZE    1952
#define WVDS_MLKEM768_PK_SIZE   1184
#define WVDS_MLKEM768_CT_SIZE   1088
#define WVDS_SHARED_SECRET_SIZE 32

// Limits
#define WVDS_MAX_PAYLOAD_SIZE   65536
#define WVDS_HEADER_SIZE        8
</code>

----

[[.:protokoll|< Protocol]] | [[.:sicherheit|Next: Security >]]