1 /* 2 * Copyrights 3 * 4 * Portions created or assigned to Cisco Systems, Inc. are 5 * Copyright (c) 2014-2016 Cisco Systems, Inc. All Rights Reserved. 6 */ 7 8 /** 9 * \file 10 * \brief 11 * Functions and data structures for interacting with 12 * JSON Web Signature (JWS) objects. 13 * 14 */ 15 16 #ifndef CJOSE_HEADER_H 17 #define CJOSE_HEADER_H 18 19 #include <stdbool.h> 20 #include "cjose/error.h" 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /** The JWE algorithm header attribute name. */ 27 extern const char *CJOSE_HDR_ALG; 28 29 /** The JWE content encryption algorithm header attribute name. */ 30 extern const char *CJOSE_HDR_ENC; 31 32 /** The JWE "cty" header attribute. */ 33 extern const char *CJOSE_HDR_CTY; 34 35 /** The Jose "kid" header attribute. */ 36 extern const char *CJOSE_HDR_KID; 37 38 /** The Jose "epk" header attribte. */ 39 extern const char *CJOSE_HDR_EPK; 40 41 /** For ECDH-ES algorithms, the PartyU and PartyV values */ 42 extern const char *CJOSE_HDR_APU; 43 extern const char *CJOSE_HDR_APV; 44 45 /** The JWA algorithm attribute value for none. */ 46 extern const char *CJOSE_HDR_ALG_NONE; 47 48 /** The JWE algorithm attribute value of ECDH-ES. */ 49 extern const char *CJOSE_HDR_ALG_ECDH_ES; 50 51 /** The JWE algorithm attribute value for RSA-OAEP. */ 52 extern const char *CJOSE_HDR_ALG_RSA_OAEP; 53 54 /** The JWE algorithm attribute value for RSA1_5. */ 55 extern const char *CJOSE_HDR_ALG_RSA1_5; 56 57 /** The JWE algorithm attribute value for A128KW, A192KW and A256KW. */ 58 extern const char *CJOSE_HDR_ALG_A128KW; 59 extern const char *CJOSE_HDR_ALG_A192KW; 60 extern const char *CJOSE_HDR_ALG_A256KW; 61 62 /** The JWS algorithm attribute value for PS256, PS384 and PS512. */ 63 extern const char *CJOSE_HDR_ALG_PS256; 64 extern const char *CJOSE_HDR_ALG_PS384; 65 extern const char *CJOSE_HDR_ALG_PS512; 66 67 /** The JWS algorithm attribute value for RS256, RS384 and RS512. */ 68 extern const char *CJOSE_HDR_ALG_RS256; 69 extern const char *CJOSE_HDR_ALG_RS384; 70 extern const char *CJOSE_HDR_ALG_RS512; 71 72 /** The JWS algorithm attribute values for HS256, HS384 and HS512. */ 73 extern const char *CJOSE_HDR_ALG_HS256; 74 extern const char *CJOSE_HDR_ALG_HS384; 75 extern const char *CJOSE_HDR_ALG_HS512; 76 77 /** The JWS algorithm attribute values for ES256, ES384 and ES512. */ 78 extern const char *CJOSE_HDR_ALG_ES256; 79 extern const char *CJOSE_HDR_ALG_ES384; 80 extern const char *CJOSE_HDR_ALG_ES512; 81 82 /** The JWE algorithm attribute value for "dir". */ 83 extern const char *CJOSE_HDR_ALG_DIR; 84 85 /** The JWE content encryption algorithm value for A256GCM. */ 86 extern const char *CJOSE_HDR_ENC_A256GCM; 87 88 /** The JWE content encryption algorithm value for A128CBC-HS256, A192CBC-HS384 and A256CBC-HS512. */ 89 extern const char *CJOSE_HDR_ENC_A128CBC_HS256; 90 extern const char *CJOSE_HDR_ENC_A192CBC_HS384; 91 extern const char *CJOSE_HDR_ENC_A256CBC_HS512; 92 93 /** 94 * An instance of a header object (used when creating JWE/JWS objects). 95 */ 96 typedef struct json_t cjose_header_t; 97 98 /** 99 * Instsantiates a new header object. Caller is responsible for 100 * subsequently releasing the object through cjose_header_release(). 101 * 102 * \param err [out] An optional error object which can be used to get additional 103 * information in the event of an error. 104 * \returns a newly allocated header object, or NULL if an error occurs. 105 */ 106 cjose_header_t *cjose_header_new(cjose_err *err); 107 108 /** 109 * Retains an existing header object. Callers must use this method if the 110 * header will be used past the scope it was created in (e.g., from a 111 * `cjose_jws_t` object). 112 * 113 * \param header[in] the header object to be retained. 114 * \returns the retained header object 115 */ 116 cjose_header_t *cjose_header_retain(cjose_header_t *header); 117 118 /** 119 * Releases an existing header object. Callers must use this method 120 * to dispose of header rather than directly free'ing a cjose_header 121 * object. 122 * 123 * \param header[in] the header object to be released. 124 */ 125 void cjose_header_release(cjose_header_t *header); 126 127 /** 128 * Sets a header attribute on a header object. If that header was 129 * previously set, this will replace the previous value with the new one. 130 * 131 * \param header[in] a previously instantiated header object. 132 * \param attr[in] the header attribute to be set. 133 * \param value[in] the value to assign to the header attribute. 134 * \param err [out] An optional error object which can be used to get additional 135 * information in the event of an error. 136 * \returns true if header is successfully set. 137 */ 138 bool cjose_header_set(cjose_header_t *header, const char *attr, const char *value, cjose_err *err); 139 140 /** 141 * Retrieves the value of the requested header attribute from the header 142 * object. 143 * 144 * \param header[in] a header object. 145 * \param attr[in] the header attribute to be got. 146 * \param err [out] An optional error object which can be used to get additional 147 * information in the event of an error. 148 * \returns a string containing the current value for the requested attribute. 149 * The value returned is a null terminated UTF-8 encoded string, or NULL if corresponding 150 * string header was not found. The returned value is read-only and must not be modified 151 * or freed by the user. It is valid as long as the corresponding cjose_header_t object 152 * is not released. 153 */ 154 const char *cjose_header_get(cjose_header_t *header, const char *attr, cjose_err *err); 155 156 /** 157 * Sets a raw header attribute on a header object. If that header was 158 * previously set, this will replace the previous value with the new one. 159 * The input value must be a JSON serialized string. This function does not 160 * retain pointers to specified attribute or value. 161 * 162 * \param header[in] a previously instantiated header object. 163 * \param attr[in] the header attribute to be set. 164 * \param value[in] the JSON value to assign to the header attribute. The value must 165 * be a valid JSON, and will be assigned as is. 166 */ 167 bool cjose_header_set_raw(cjose_header_t *header, const char *attr, const char *value, cjose_err *err); 168 169 /** 170 * Retrieves the raw value of the requested header attribute from the header 171 * object. 172 * \param header[in] a header object. 173 * \param attr[in] the header attribute to be got. 174 * \param err [out] An optional error object which can be used to get additional 175 * information in the event of an error. 176 * \returns a string containing the current JSON value for the requested attribute. 177 */ 178 char *cjose_header_get_raw(cjose_header_t *header, const char *attr, cjose_err *err); 179 180 #ifdef __cplusplus 181 } 182 #endif 183 184 #endif // CJOSE_HEADER_H 185