cert.h (6123B)
1 ///file @cert.h 2 #ifndef LIBQAEDA_CERT_H_ 3 #define LIBQAEDA_CERT_H_ 4 5 #include <stddef.h> 6 7 #include "lq/crypto.h" 8 #include "lq/msg.h" 9 #include "lq/store.h" 10 11 #ifndef LQ_CERT_DOMAIN_LEN 12 #define LQ_CERT_DOMAIN_LEN 8 13 #endif 14 15 /** 16 * \struct LQCert 17 * 18 * \brief A certificate is a counter-signed piece of arbitrary data within a designated domain. It may or may not be linked to a previous certificate. 19 * 20 * \see lq_certificate_t 21 */ 22 typedef struct lq_certificate_t LQCert; 23 struct lq_certificate_t { 24 char domain[LQ_CERT_DOMAIN_LEN]; ///< Domain data is used by application data to evaluate whether a record is relevant for it or not. 25 LQMsg *request; ///< A request message encapsulates an arbitrary string of data that should be confirmed by a responder. 26 LQSig *request_sig; ///< Signature over a request message and the linked certificate. If the linked certificate is NULL, the certificate data used in the signature with be a LQ_DIGEST_LEN string with all bytes set to 0. 27 LQMsg *response; ///< A response message encapsulates an arbitrary string of data that confirms a request. This field must be NULL unless a signed requests exists. 28 LQSig *response_sig; ///< Signature over a response message. This field must be NULL unless a response message is set. The signature is calculated over both the response and the signed request. 29 LQCert *parent; ///< Link to previous certificate. Optional. Set to NULL if no link exists. 30 char parent_hash[LQ_DIGEST_LEN]; 31 }; 32 33 /** 34 * \brief Create a new certificate. 35 * 36 * \param[in] Previous certificate to link to. 37 * \param[in] Context to control behavior of certificate processing. If NULL, default behavior will be used. 38 * \param[in] Request message. 39 * \param[in] Response message. 40 * \return The allocated certificate object. It is the caller's responsibility to free the object. 41 * \todo request and response message does not make sense to set without option to set signature, factor out to separate functions. 42 * \see lq_certificate_free 43 */ 44 LQCert* lq_certificate_new(LQCert *parent); 45 46 /** 47 * @brief Set the domain of the certificate. If not set, the default domain value will be used, which is LQ_DOMAIN_LEN bytes set to 0. 48 * @param[in] Instantiated certificate to set domain on. 49 * @param[in] Domain data. Must be LQ_DOMAIN_LEN bytes long. 50 */ 51 void lq_certificate_set_domain(LQCert *cert, const char *domain); 52 53 /** 54 * @brief Sign the next pending message in the certificate. If the request message is set but not signed, the request message will be signed. If the response message is set but not signed, the response message will be signed. The limitations described in the struct declaration apply. 55 * 56 * Depending on the state of the certificate, additional data will be prepended to the message before calculating the digest, where <value> means a required value, [value] means and optional value, and "|" means concatenate. 57 * 58 * <domain> | [ parent | ] [ request_signature | ] [ response_signature | ] 59 * 60 * If the certificate is linked to another certificate, then the digest of that certificate will be calculated and used as the "parent" value. Note that a linked certificate must be finalized, meaning it must have a valid response signature. 61 * 62 * If the certificate has the request_signature it will be used as the request_signature value. 63 * 64 * If the certificate has the response_signature it will be used as the response_signature value. The response_signature may not exist without the request_signature. 65 * 66 * @param[in] Instantiated certificate to perform signature on. 67 * @param[in] Private key to use for signature. 68 * @return ERR_OK on successful signature, or: 69 * * ERR_REQUEST if request has already been signed (and response is not set) 70 * * ERR_RESPONSE if response has already been signed. 71 * * ERR_ENCODING if calculateing the signature failed. 72 * * ERR_INIT if no message eligible for signature exists. 73 */ 74 int lq_certificate_sign(LQCert *cert, LQPrivKey *pk); 75 76 /** 77 * @brief Serialize certificate data payload for storage and transport. 78 * @param[in] Certificate to serialize 79 * @param[out] Buffer to write data to. 80 * @param[out] Value behind pointer must contain the capacity of the output buffer. Will be overwritten with the actual number of bytes written. 81 * @param[in] Store implementations to use for storing serialized certificate and message data. 82 * @return ERR_OK if serialization is successful, or: 83 * * ERR_INIT if the serialization object couldn't be instantiated. 84 * * ERR_OVERFLOW if output exceeded the available space in output buffer. 85 * * ERR_WRITE if serialization of an element failed. 86 * * ERR_ENCODING if generating the final serialization string failed. 87 */ 88 int lq_certificate_serialize(LQCert *cert, char *out, size_t *out_len, LQResolve *resolve); 89 90 /** 91 * @brief Deserialize certificate data payload from storage or transport. 92 * @param[out] Pointer to instantiated certificate. It is the caller's responsibility to free the certificate object. 93 * @param[in] Serialized data. 94 * @param[in] Length of serialized data. 95 * @param[in] Store implementations to use for resolving content key from deserialized message and certificate data. 96 * @return ERR_OK if deserialization is successful, or: 97 * * ERR_INIT if the serialization object couldn't be instantiated. 98 * * ERR_READ if deserialization of an element failed. 99 * * ERR_ENCODING if interpretation of the serialized data failed. 100 * @see lq_certificate_free 101 */ 102 int lq_certificate_deserialize(LQCert **cert, char *in, size_t in_len, LQResolve *resolve); 103 104 105 /** 106 * @brief UNIMPLEMENTED verify the integrity of a certificate. Specifically that signatures in the certificate match given keys and data. 107 * @param[in] Certificate to verify 108 * @return ERR_OK if verified, or: 109 * .... 110 */ 111 int lq_certificate_verify(LQCert *cert, LQPubKey *req_key, LQPubKey *res_key); 112 113 114 int lq_certificate_request(LQCert *cert, LQMsg *req, LQPrivKey *pk); 115 116 int lq_certificate_respond(LQCert *cert, LQMsg *rsp, LQPrivKey *pk); 117 118 119 /** 120 * @brief Free an instantiated certificate. 121 * @param[in] Certificate to free. 122 */ 123 void lq_certificate_free(LQCert *cert); 124 125 #endif // LIBQAEDA_CERT_H_