cert.h (7640B)
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 * \return The allocated certificate object. It is the caller's responsibility to free the object. 38 * 39 * \see lq_certificate_free 40 */ 41 LQCert* lq_certificate_new(LQCert *parent); 42 43 /** 44 * \brief Set the domain of the certificate. 45 * 46 * If not set, the default domain value will be used, which is LQ_DOMAIN_LEN bytes set to 0. 47 * 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. 55 * 56 * 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. 57 * 58 * 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. 59 * 60 * <domain> | [ parent | ] [ request_signature | ] [ response_signature | ] 61 * 62 * 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. 63 * 64 * If the certificate has the request_signature it will be used as the request_signature value. 65 * 66 * 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. 67 * 68 * \param[in] Instantiated certificate to perform signature on. 69 * \param[in] Private key to use for signature. 70 * \return ERR_OK on successful signature, or: 71 * * ERR_REQUEST if request has already been signed (and response is not set) 72 * * ERR_RESPONSE if response has already been signed. 73 * * ERR_ENCODING if calculateing the signature failed. 74 * * ERR_INIT if no message eligible for signature exists. 75 * 76 * \see lq_certificate_request 77 * \see lq_certificate_respond 78 */ 79 int lq_certificate_sign(LQCert *cert, LQPrivKey *pk); 80 81 /** 82 * \brief Serialize certificate data payload for storage and transport. 83 * 84 * \param[in] Certificate to serialize 85 * \param[in] Store implementations to use for storing serialized certificate and message data. If NULL, content will not be stored in resolver. 86 * \param[out] Buffer to write data to. 87 * \param[out] Value behind pointer must contain the capacity of the output buffer. Will be overwritten with the actual number of bytes written. 88 * \return ERR_OK if serialization is successful, or: 89 * * ERR_INIT if the serialization object couldn't be instantiated. 90 * * ERR_OVERFLOW if output exceeded the available space in output buffer. 91 * * ERR_WRITE if serialization of an element failed. 92 * * ERR_ENCODING if generating the final serialization string failed. 93 */ 94 int lq_certificate_serialize(LQCert *cert, LQResolve *resolve, char *out, size_t *out_len); 95 96 /** 97 * \brief Deserialize certificate data payload from storage or transport. 98 * 99 * \param[out] Pointer to where certificate will be instantiated. It is the caller's responsibility to free the certificate object. 100 * \param[in] Store implementations to use for resolving content key from deserialized message and certificate data. If NULL, content will not be resolved. 101 * \param[in] Serialized data. 102 * \param[in] Length of serialized data. 103 * \return ERR_OK if deserialization is successful, or: 104 * * ERR_INIT if the serialization object couldn't be instantiated. 105 * * ERR_READ if deserialization of an element failed. 106 * * ERR_ENCODING if interpretation of the serialized data failed. 107 * \see lq_certificate_free 108 */ 109 int lq_certificate_deserialize(LQCert **cert, LQResolve *resolve, char *in, size_t in_len); 110 111 112 /** 113 * \brief Verify the integrity of a certificate. Specifically that signatures in the certificate match given keys and data. 114 * 115 * The cert must have either 116 * - no message (NOOP) 117 * - request message and request_message signature 118 * - request AND response message, with request AND response signatures 119 * 120 * Messages must have public key set. 121 * 122 * The public key pointers in the output parameters are valid until the certificate is freed. 123 * 124 * \param[in] Certificate to verify 125 * \param[out] If not NULL, provides location to store pointer to request publickey. If certificate does not contain a valid request, this will be set to NULL. 126 * \param[out] If not NULL, provider location to store pointer to response publickey. If certificate does not contain a valid response, this will be set to NULL. 127 * \return ERR_OK if verified, ERR_NOOP if no message. 128 */ 129 int lq_certificate_verify(LQCert *cert, LQPubKey **request_pubkey, LQPubKey **response_pubkey); 130 131 132 /*** 133 * \brief Add and optionally sign a request message to the certificate. 134 * 135 * The signature will be calculated over the certificate data. 136 * 137 * Fails if a request or response message and/or signature already exists. 138 * 139 * Message is freed as part of lq_certificate_free. 140 * 141 * \param[in] Certificate to manipulate. 142 * \param[in] Request message 143 * \param[in] If not NULL, sign request with the given private key. 144 * \return ERR_OK on success. 145 */ 146 int lq_certificate_request(LQCert *cert, LQMsg *req, LQPrivKey *pk); 147 148 /*** 149 * \brief Add and optionally sign a response message to the certificate. 150 * 151 * The signature will be calculated over the certificate data and the existing request. 152 * 153 * Fails if a request and/or signature does not exist. 154 * 155 * Fails if a response and/or signature already exists. 156 * 157 * Message is freed as part of lq_certificate_free. 158 * 159 * \param[in] Certificate to manipulate. 160 * \param[in] Response message 161 * \param[in] If not NULL, sign response with the given private key. 162 * \return ERR_OK on success. 163 */ 164 int lq_certificate_respond(LQCert *cert, LQMsg *rsp, LQPrivKey *pk); 165 166 167 /** 168 * \brief Free an instantiated certificate. 169 * 170 * \param[in] Certificate to free. 171 */ 172 void lq_certificate_free(LQCert *cert); 173 174 #endif // LIBQAEDA_CERT_H_