Rhonabwy: JWE functions

Rhonabwy Create, modify, parse or export Json Web Keys as defined in the RFC 7517

Functions
JWE functions

## Functions
jwe_t * | r_jwe_copy (jwe_t *jwe)
int | r_jwe_set_payload (jwe_t *jwe, const unsigned char *payload, size_t payload_len)
const unsigned char * | r_jwe_get_payload (jwe_t *jwe, size_t *payload_len)
int | r_jwe_set_alg (jwe_t *jwe, jwa_alg alg)
jwa_alg | r_jwe_get_alg (jwe_t *jwe)
int | r_jwe_set_enc (jwe_t *jwe, jwa_enc enc)
jwa_enc | r_jwe_get_enc (jwe_t *jwe)
int | r_jwe_set_header_str_value (jwe_t *jwe, const char *key, const char *str_value)
int | r_jwe_set_header_int_value (jwe_t *jwe, const char *key, int i_value)
int | r_jwe_set_header_json_t_value (jwe_t *jwe, const char *key, json_t *j_value)
const char * | r_jwe_get_header_str_value (jwe_t *jwe, const char *key)
int | r_jwe_get_header_int_value (jwe_t *jwe, const char *key)
json_t * | r_jwe_get_header_json_t_value (jwe_t *jwe, const char *key)
json_t * | r_jwe_get_full_header_json_t (jwe_t *jwe)
int | r_jwe_add_keys (jwe_t *jwe, jwk_t *jwk_privkey, jwk_t *jwk_pubkey)
int | r_jwe_add_jwks (jwe_t *jwe, jwks_t *jwks_privkey, jwks_t *jwks_pubkey)
int | r_jwe_add_keys_json_str (jwe_t *jwe, const char *privkey, const char *pubkey)
int | r_jwe_add_keys_json_t (jwe_t *jwe, json_t *privkey, json_t *pubkey)
int | r_jwe_add_keys_pem_der (jwe_t *jwe, int format, const unsigned char *privkey, size_t privkey_len, const unsigned char *pubkey, size_t pubkey_len)
int | r_jwe_add_keys_gnutls (jwe_t *jwe, gnutls_privkey_t privkey, gnutls_pubkey_t pubkey)
int | r_jwe_add_key_symmetric (jwe_t *jwe, const unsigned char *key, size_t key_len)
jwks_t * | r_jwe_get_jwks_privkey (jwe_t *jwe)
jwks_t * | r_jwe_get_jwks_pubkey (jwe_t *jwe)
int | r_jwe_set_cypher_key (jwe_t *jwe, const unsigned char *key, size_t key_len)
const unsigned char * | r_jwe_get_cypher_key (jwe_t *jwe, size_t *key_len)
int | r_jwe_generate_cypher_key (jwe_t *jwe)
int | r_jwe_set_iv (jwe_t *jwe, const unsigned char *iv, size_t iv_len)
const unsigned char * | r_jwe_get_iv (jwe_t *jwe, size_t *iv_len)
int | r_jwe_generate_iv (jwe_t *jwe)
int | r_jwe_encrypt_payload (jwe_t *jwe)
int | r_jwe_decrypt_payload (jwe_t *jwe)
int | r_jwe_encrypt_key (jwe_t *jwe, jwk_t *jwk_pubkey, int x5u_flags)
int | r_jwe_decrypt_key (jwe_t *jwe, jwk_t *jwk_privkey, int x5u_flags)
int | r_jwe_parse (jwe_t *jwe, const char *jwe_str, int x5u_flags)
int | r_jwe_parsen (jwe_t *jwe, const char *jwe_str, size_t jwe_str_len, int x5u_flags)
int | r_jwe_decrypt (jwe_t *jwe, jwk_t *jwk_privkey, int x5u_flags)
char * | r_jwe_serialize (jwe_t *jwe, jwk_t *jwk_pubkey, int x5u_flags)

## Detailed Description

Manage JSON Web Encryption

## Function Documentation

## ◆ r_jwe_copy()

jwe_t* r_jwe_copy | ( | jwe_t * | jwe | ) |

Return a copy of the JWE

Parameters

  jwe | the jwe_t to duplicate

Returns
  a copy of jwe

## ◆ r_jwe_set_payload()

int r_jwe_set_payload | ( | jwe_t * | jwe,
|  | const unsigned char * | payload,
|  | size_t | payload_len
| ) |  |

Set the payload of the jwe

Parameters

  jwe | the jwe_t to update
  payload | the payload to set
  payload_len | the size of the payload

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_get_payload()

const unsigned char* r_jwe_get_payload | ( | jwe_t * | jwe,
|  | size_t * | payload_len
| ) |  |

Get the JWE payload

Parameters

  jwe | the jwe_t to get the payload from
  payload_len | the length of the JWE payload, may be NULL

Returns
  a pointer to the JWE payload

## ◆ r_jwe_set_alg()

int r_jwe_set_alg | ( | jwe_t * | jwe,
|  | jwa_alg | alg
| ) |  |

Set the JWE alg to use for key encryption

Parameters

  jwe | the jwe_t to update
  alg | the algorithm to use

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_get_alg()

jwa_alg r_jwe_get_alg | ( | jwe_t * | jwe | ) |

Get the JWE alg used for key encryption

Parameters

  jwe | the jwe_t to update

Returns
  the algorithm used

## ◆ r_jwe_set_enc()

int r_jwe_set_enc | ( | jwe_t * | jwe,
|  | jwa_enc | enc
| ) |  |

Set the JWE enc to use for payload encryption

Parameters

  jwe | the jwe_t to update
  enc | the encorithm to use

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_get_enc()

jwa_enc r_jwe_get_enc | ( | jwe_t * | jwe | ) |

Get the JWE enc used for payload encryption

Parameters

  jwe | the jwe_t to update

Returns
  the encorithm used

## ◆ r_jwe_set_header_str_value()

int r_jwe_set_header_str_value | ( | jwe_t * | jwe,
|  | const char * | key,
|  | const char * | str_value
| ) |  |

Adds a string value to the JWE header

Parameters

  jwe | the jwe_t to update
  key | the key to set to the JWE header
  str_value | the value to set

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_set_header_int_value()

int r_jwe_set_header_int_value | ( | jwe_t * | jwe,
|  | const char * | key,
|  | int | i_value
| ) |  |

Adds an integer value to the JWE header

Parameters

  jwe | the jwe_t to update
  key | the key to set to the JWE header
  i_value | the value to set

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_set_header_json_t_value()

int r_jwe_set_header_json_t_value | ( | jwe_t * | jwe,
|  | const char * | key,
|  | json_t * | j_value
| ) |  |

Adds a JSON value to the JWE header

Parameters

  jwe | the jwe_t to update
  key | the key to set to the JWE header
  j_value | the value to set

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_get_header_str_value()

const char* r_jwe_get_header_str_value | ( | jwe_t * | jwe,
|  | const char * | key
| ) |  |

Gets a string value from the JWE header

Parameters

  jwe | the jwe_t to get the value
  key | the key to retreive the value

Returns
  a string value, NULL if not present

## ◆ r_jwe_get_header_int_value()

int r_jwe_get_header_int_value | ( | jwe_t * | jwe,
|  | const char * | key
| ) |  |

Gets an integer value from the JWE header

Parameters

  jwe | the jwe_t to get the value
  key | the key to retreive the value

Returns
  an int value, 0 if not present

## ◆ r_jwe_get_header_json_t_value()

json_t* r_jwe_get_header_json_t_value | ( | jwe_t * | jwe,
|  | const char * | key
| ) |  |

Gets a JSON value from the JWE header

Parameters

  jwe | the jwe_t to get the value
  key | the key to retreive the value

Returns
  a json_t * value, NULL if not present

## ◆ r_jwe_get_full_header_json_t()

json_t* r_jwe_get_full_header_json_t | ( | jwe_t * | jwe | ) |

Return the full JWE header in JSON format

Parameters

  jwe | the jwe_t to get the value

Returns
  a json_t * value

## ◆ r_jwe_add_keys()

int r_jwe_add_keys | ( | jwe_t * | jwe,
|  | jwk_t * | jwk_privkey,
|  | jwk_t * | jwk_pubkey
| ) |  |

Adds private and/or public keys for the cypher key encryption and decryption

Parameters

  jwe | the jwe_t to update
  jwk_privkey | the private key in jwk_t * format, can be NULL
  jwk_pubkey | the public key in jwk_t * format, can be NULL

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_add_jwks()

int r_jwe_add_jwks | ( | jwe_t * | jwe,
|  | jwks_t * | jwks_privkey,
|  | jwks_t * | jwks_pubkey
| ) |  |

Adds private and/or public keys sets for the cypher key encryption and decryption

Parameters

  jwe | the jwe_t to update
  jwks_privkey | the private key set in jwks_t * format, can be NULL
  jwks_pubkey | the public key set in jwks_t * format, can be NULL

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_add_keys_json_str()

int r_jwe_add_keys_json_str | ( | jwe_t * | jwe,
|  | const char * | privkey,
|  | const char * | pubkey
| ) |  |

Add keys to perform encryption ot decryption keys must be a JWK stringified

Parameters

  jwe | the jwe_t to update
  privkey | the private key to enc the
  pubkey | the public key to verify the encature

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_add_keys_json_t()

int r_jwe_add_keys_json_t | ( | jwe_t * | jwe,
|  | json_t * | privkey,
|  | json_t * | pubkey
| ) |  |

Add keys to perform encryption ot decryption keys must be a JWK in json_t * format

Parameters

  jwe | the jwe_t to update
  privkey | the private key to enc the
  pubkey | the public key to verify the encature

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_add_keys_pem_der()

int r_jwe_add_keys_pem_der | ( | jwe_t * | jwe,
|  | int | format,
|  | const unsigned char * | privkey,
|  | size_t | privkey_len,
|  | const unsigned char * | pubkey,
|  | size_t | pubkey_len
| ) |  |

Add keys to perform encryption ot decryption keys must be in PEM or DER format

Parameters

  jwe | the jwe_t to update
  format | the format of the input, values available are R_FORMAT_PEM or R_FORMAT_DER
  privkey | the private key to sign the
  privkey_len | length of privkey
  pubkey | the public key to verify the signature
  pubkey_len | length of pubkey

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_add_keys_gnutls()

int r_jwe_add_keys_gnutls | ( | jwe_t * | jwe,
|  | gnutls_privkey_t | privkey,
|  | gnutls_pubkey_t | pubkey
| ) |  |

Add keys to perform encryption ot decryption keys must be gnutls key structures

Parameters

  jwe | the jwe_t to update
  privkey | the private key to enc the
  pubkey | the public key to verify the encature

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_add_key_symmetric()

int r_jwe_add_key_symmetric | ( | jwe_t * | jwe,
|  | const unsigned char * | key,
|  | size_t | key_len
| ) |  |

Add symmetric key by value to perform encryption ot decryption

Parameters

  jwe | the jwe_t to update
  key | the raw key value
  key_len | the length of the key

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_get_jwks_privkey()

jwks_t* r_jwe_get_jwks_privkey | ( | jwe_t * | jwe | ) |

Get private keys set for the cypher key decryption

Parameters

  jwe | the jwe_t to get the value

Returns
  the private key set in jwks_t * format

## ◆ r_jwe_get_jwks_pubkey()

jwks_t* r_jwe_get_jwks_pubkey | ( | jwe_t * | jwe | ) |

Get public keys set for the cypher key encryption

Parameters

  jwe | the jwe_t to get the value

Returns
  the public key set in jwks_t * format

## ◆ r_jwe_set_cypher_key()

int r_jwe_set_cypher_key | ( | jwe_t * | jwe,
|  | const unsigned char * | key,
|  | size_t | key_len
| ) |  |

Sets the cypher key to encrypt or decrypt the payload

Parameters

  jwe | the jwe_t to update
  key | the key to encrypt or decrypt the payload
  key_len | the size of the key

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_get_cypher_key()

const unsigned char* r_jwe_get_cypher_key | ( | jwe_t * | jwe,
|  | size_t * | key_len
| ) |  |

Gets the cypher key to encrypt or decrypt the payload

Parameters

  jwe | the jwe_t to get the value
  key_len | set the size of the key, may be NULL

Returns
  the key to encrypt or decrypt the payload

## ◆ r_jwe_generate_cypher_key()

int r_jwe_generate_cypher_key | ( | jwe_t * | jwe | ) |

Generates a random cypher key

Parameters

  jwe | the jwe_t to update

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_set_iv()

int r_jwe_set_iv | ( | jwe_t * | jwe,
|  | const unsigned char * | iv,
|  | size_t | iv_len
| ) |  |

Sets the Initialization Vector (iv)

Parameters

  jwe | the jwe_t to update
  iv | the iv to set
  iv_len | the size of the iv

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_get_iv()

const unsigned char* r_jwe_get_iv | ( | jwe_t * | jwe,
|  | size_t * | iv_len
| ) |  |

Gets the Initialization Vector (iv)

Parameters

  jwe | the jwe_t to get the value
  iv_len | set the size of the iv, may be NULL

Returns
  the iv

## ◆ r_jwe_generate_iv()

int r_jwe_generate_iv | ( | jwe_t * | jwe | ) |

Generates a random Initialization Vector (iv)

Parameters

  jwe | the jwe_t to update

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_encrypt_payload()

int r_jwe_encrypt_payload | ( | jwe_t * | jwe | ) |

Encrypts the payload using its key and iv

Parameters

  jwe | the jwe_t to update

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_decrypt_payload()

int r_jwe_decrypt_payload | ( | jwe_t * | jwe | ) |

Decrypts the payload using its key and iv

Parameters

  jwe | the jwe_t to update

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_encrypt_key()

int r_jwe_encrypt_key | ( | jwe_t * | jwe,
|  | jwk_t * | jwk_pubkey,
|  | int | x5u_flags
| ) |  |

Encrypts the key

Parameters

  jwe | the jwe_t to update
  jwk_pubkey | the jwk to encrypt the key, may be NULL
  x5u_flags | Flags to retrieve x5u certificates pointed by x5u if necessary, could be 0 if not needed Flags available are R_FLAG_IGNORE_SERVER_CERTIFICATE: ignrore if web server certificate is invalid R_FLAG_FOLLOW_REDIRECT: follow redirections if necessary R_FLAG_IGNORE_REMOTE: do not download remote key, but the function may return an error

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_decrypt_key()

int r_jwe_decrypt_key | ( | jwe_t * | jwe,
|  | jwk_t * | jwk_privkey,
|  | int | x5u_flags
| ) |  |

Decrypts the key

Parameters

  jwe | the jwe_t to update
  jwk_privkey | the jwk to decrypt the key, may be NULL
  x5u_flags | Flags to retrieve x5u certificates pointed by x5u if necessary, could be 0 if not needed Flags available are R_FLAG_IGNORE_SERVER_CERTIFICATE: ignrore if web server certificate is invalid R_FLAG_FOLLOW_REDIRECT: follow redirections if necessary R_FLAG_IGNORE_REMOTE: do not download remote key, but the function may return an error

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_parse()

int r_jwe_parse | ( | jwe_t * | jwe,
|  | const char * | jwe_str,
|  | int | x5u_flags
| ) |  |

Parses the JWE

Parameters

  jwe | the jwe_t to update
  jwe_str | the jwe serialized to parse, must end with a NULL string terminator
  x5u_flags | Flags to retrieve x5u certificates pointed by x5u if necessary, could be 0 if not needed Flags available are R_FLAG_IGNORE_SERVER_CERTIFICATE: ignrore if web server certificate is invalid R_FLAG_FOLLOW_REDIRECT: follow redirections if necessary R_FLAG_IGNORE_REMOTE: do not download remote key, but the function may return an error

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_parsen()

int r_jwe_parsen | ( | jwe_t * | jwe,
|  | const char * | jwe_str,
|  | size_t | jwe_str_len,
|  | int | x5u_flags
| ) |  |

Parses the JWE

Parameters

  jwe | the jwe_t to update
  jwe_str | the jwe serialized to parse
  jwe_str_len | the length of jwe_str
  x5u_flags | Flags to retrieve x5u certificates pointed by x5u if necessary, could be 0 if not needed Flags available are R_FLAG_IGNORE_SERVER_CERTIFICATE: ignrore if web server certificate is invalid R_FLAG_FOLLOW_REDIRECT: follow redirections if necessary R_FLAG_IGNORE_REMOTE: do not download remote key, but the function may return an error

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_decrypt()

int r_jwe_decrypt | ( | jwe_t * | jwe,
|  | jwk_t * | jwk_privkey,
|  | int | x5u_flags
| ) |  |

Decrypts the payload of the JWE

Parameters

  jwe | the jwe_t to update
  jwk_privkey | the private key to decrypt cypher key, can be NULL if jwe already contains a private key
  x5u_flags | Flags to retrieve x5u certificates pointed by x5u if necessary, could be 0 if not needed Flags available are R_FLAG_IGNORE_SERVER_CERTIFICATE: ignrore if web server certificate is invalid R_FLAG_FOLLOW_REDIRECT: follow redirections if necessary R_FLAG_IGNORE_REMOTE: do not download remote key, but the function may return an error

Returns
  RHN_OK on success, an error value on error

## ◆ r_jwe_serialize()

char* r_jwe_serialize | ( | jwe_t * | jwe,
|  | jwk_t * | jwk_pubkey,
|  | int | x5u_flags
| ) |  |

Serialize a JWE into its string format (aaa.bbb.ccc.xxx.yyy.zzz)

Parameters

  jwe | the JWE to serialize
  jwk_pubkey | the public key to encrypt the cypher key, can be NULL if jwe already contains a public key
  x5u_flags | Flags to retrieve x5u certificates pointed by x5u if necessary, could be 0 if not needed Flags available are R_FLAG_IGNORE_SERVER_CERTIFICATE: ignrore if web server certificate is invalid R_FLAG_FOLLOW_REDIRECT: follow redirections if necessary R_FLAG_IGNORE_REMOTE: do not download remote key, but the function may return an error

Returns
  the JWE in serialized format, returned value must be r_free'd after use