Rhonabwy: JWS functions

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

Functions
JWS functions

## Functions
jws_t * | r_jws_copy (jws_t *jws)
int | r_jws_set_payload (jws_t *jws, const unsigned char *payload, size_t payload_len)
const unsigned char * | r_jws_get_payload (jws_t *jws, size_t *payload_len)
int | r_jws_set_alg (jws_t *jws, jwa_alg alg)
jwa_alg | r_jws_get_alg (jws_t *jws)
int | r_jws_set_header_str_value (jws_t *jws, const char *key, const char *str_value)
int | r_jws_set_header_int_value (jws_t *jws, const char *key, int i_value)
int | r_jws_set_header_json_t_value (jws_t *jws, const char *key, json_t *j_value)
const char * | r_jws_get_header_str_value (jws_t *jws, const char *key)
int | r_jws_get_header_int_value (jws_t *jws, const char *key)
json_t * | r_jws_get_header_json_t_value (jws_t *jws, const char *key)
json_t * | r_jws_get_full_header_json_t (jws_t *jws)
int | r_jws_add_keys (jws_t *jws, jwk_t *jwk_privkey, jwk_t *jwk_pubkey)
int | r_jws_add_jwks (jws_t *jws, jwks_t *jwks_privkey, jwks_t *jwks_pubkey)
int | r_jws_add_keys_json_str (jws_t *jws, const char *privkey, const char *pubkey)
int | r_jws_add_keys_json_t (jws_t *jws, json_t *privkey, json_t *pubkey)
int | r_jws_add_keys_pem_der (jws_t *jws, int format, const unsigned char *privkey, size_t privkey_len, const unsigned char *pubkey, size_t pubkey_len)
int | r_jws_add_keys_gnutls (jws_t *jws, gnutls_privkey_t privkey, gnutls_pubkey_t pubkey)
int | r_jws_add_key_symmetric (jws_t *jws, const unsigned char *key, size_t key_len)
jwks_t * | r_jws_get_jwks_privkey (jws_t *jws)
jwks_t * | r_jws_get_jwks_pubkey (jws_t *jws)
int | r_jws_parse (jws_t *jws, const char *jws_str, int x5u_flags)
int | r_jws_parsen (jws_t *jws, const char *jws_str, size_t jws_str_len, int x5u_flags)
int | r_jws_verify_signature (jws_t *jws, jwk_t *jwk_pubkey, int x5u_flags)
char * | r_jws_serialize (jws_t *jws, jwk_t *jwk_privkey, int x5u_flags)

## Detailed Description

Manage JSON Web Signatures

## Function Documentation

## ◆ r_jws_copy()

jws_t* r_jws_copy | ( | jws_t * | jws | ) |

Return a copy of the JWS

Parameters

  jws | the jws_t to duplicate

Returns
  a copy of jws

## ◆ r_jws_set_payload()

int r_jws_set_payload | ( | jws_t * | jws,
|  | const unsigned char * | payload,
|  | size_t | payload_len
| ) |  |

Set the payload of the jws

Parameters

  jws | the jws_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_jws_get_payload()

const unsigned char* r_jws_get_payload | ( | jws_t * | jws,
|  | size_t * | payload_len
| ) |  |

Get the JWS payload

Parameters

  jws | the jws_t to get the payload from
  payload_len | the length of the JWS payload, may be NULL

Returns
  a pointer to the JWS payload

## ◆ r_jws_set_alg()

int r_jws_set_alg | ( | jws_t * | jws,
|  | jwa_alg | alg
| ) |  |

Set the JWS alg to use for signature

Parameters

  jws | the jws_t to update
  alg | the algorithm to use

Returns
  RHN_OK on success, an error value on error

## ◆ r_jws_get_alg()

jwa_alg r_jws_get_alg | ( | jws_t * | jws | ) |

Get the JWS alg used for signature

Parameters

  jws | the jws_t to update

Returns
  the algorithm used

## ◆ r_jws_set_header_str_value()

int r_jws_set_header_str_value | ( | jws_t * | jws,
|  | const char * | key,
|  | const char * | str_value
| ) |  |

Adds a string value to the JWS header

Parameters

  jws | the jws_t to update
  key | the key to set to the JWS header
  str_value | the value to set

Returns
  RHN_OK on success, an error value on error

## ◆ r_jws_set_header_int_value()

int r_jws_set_header_int_value | ( | jws_t * | jws,
|  | const char * | key,
|  | int | i_value
| ) |  |

Adds an integer value to the JWS header

Parameters

  jws | the jws_t to update
  key | the key to set to the JWS header
  i_value | the value to set

Returns
  RHN_OK on success, an error value on error

## ◆ r_jws_set_header_json_t_value()

int r_jws_set_header_json_t_value | ( | jws_t * | jws,
|  | const char * | key,
|  | json_t * | j_value
| ) |  |

Adds a JSON value to the JWS header

Parameters

  jws | the jws_t to update
  key | the key to set to the JWS header
  j_value | the value to set

Returns
  RHN_OK on success, an error value on error

## ◆ r_jws_get_header_str_value()

const char* r_jws_get_header_str_value | ( | jws_t * | jws,
|  | const char * | key
| ) |  |

Gets a string value from the JWS header

Parameters

  jws | the jws_t to get the value
  key | the key to retreive the value

Returns
  a string value, NULL if not present

## ◆ r_jws_get_header_int_value()

int r_jws_get_header_int_value | ( | jws_t * | jws,
|  | const char * | key
| ) |  |

Gets an integer value from the JWS header

Parameters

  jws | the jws_t to get the value
  key | the key to retreive the value

Returns
  an int value, 0 if not present

## ◆ r_jws_get_header_json_t_value()

json_t* r_jws_get_header_json_t_value | ( | jws_t * | jws,
|  | const char * | key
| ) |  |

Gets a JSON value from the JWS header

Parameters

  jws | the jws_t to get the value
  key | the key to retreive the value

Returns
  a json_t * value, NULL if not present

## ◆ r_jws_get_full_header_json_t()

json_t* r_jws_get_full_header_json_t | ( | jws_t * | jws | ) |

Return the full JWS header in JSON format

Parameters

  jws | the jws_t to get the value

Returns
  a json_t * value

## ◆ r_jws_add_keys()

int r_jws_add_keys | ( | jws_t * | jws,
|  | jwk_t * | jwk_privkey,
|  | jwk_t * | jwk_pubkey
| ) |  |

Sets the private and public keys for the signature and verification

Parameters

  jws | the jws_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_jws_add_jwks()

int r_jws_add_jwks | ( | jws_t * | jws,
|  | jwks_t * | jwks_privkey,
|  | jwks_t * | jwks_pubkey
| ) |  |

Adds private and/or public keys sets for the signature and verification

Parameters

  jws | the jws_t to update
  jwks_privkey | the private key set in jwk_t * format, can be NULL
  jwks_pubkey | the public key set in jwk_t * format, can be NULL

Returns
  RHN_OK on success, an error value on error

## ◆ r_jws_add_keys_json_str()

int r_jws_add_keys_json_str | ( | jws_t * | jws,
|  | const char * | privkey,
|  | const char * | pubkey
| ) |  |

Add keys to perform signature or signature verification keys must be a JWK stringified

Parameters

  jws | the jws_t to update
  privkey | the private key to sign
  pubkey | the public key to verify the signature

Returns
  RHN_OK on success, an error value on error

## ◆ r_jws_add_keys_json_t()

int r_jws_add_keys_json_t | ( | jws_t * | jws,
|  | json_t * | privkey,
|  | json_t * | pubkey
| ) |  |

Add keys to perform signature or signature verification keys must be a JWK in json_t * format

Parameters

  jws | the jws_t to update
  privkey | the private key to sign the
  pubkey | the public key to verify the signature

Returns
  RHN_OK on success, an error value on error

## ◆ r_jws_add_keys_pem_der()

int r_jws_add_keys_pem_der | ( | jws_t * | jws,
|  | int | format,
|  | const unsigned char * | privkey,
|  | size_t | privkey_len,
|  | const unsigned char * | pubkey,
|  | size_t | pubkey_len
| ) |  |

Add keys to perform signature or signature verification keys must be in PEM or DER format

Parameters

  jws | the jws_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_jws_add_keys_gnutls()

int r_jws_add_keys_gnutls | ( | jws_t * | jws,
|  | gnutls_privkey_t | privkey,
|  | gnutls_pubkey_t | pubkey
| ) |  |

Add keys to perform signature or signature verification keys must be gnutls key structures

Parameters

  jws | the jws_t to update
  privkey | the private key to sign the
  pubkey | the public key to verify the signature

Returns
  RHN_OK on success, an error value on error

## ◆ r_jws_add_key_symmetric()

int r_jws_add_key_symmetric | ( | jws_t * | jws,
|  | const unsigned char * | key,
|  | size_t | key_len
| ) |  |

Add symmetric key by value to perform signature or signature verification

Parameters

  jws | the jws_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_jws_get_jwks_privkey()

jwks_t* r_jws_get_jwks_privkey | ( | jws_t * | jws | ) |

Get private keys set for the signature

Parameters

  jws | the jws_t to get the value

Returns
  the private key set in jwks_t * format

## ◆ r_jws_get_jwks_pubkey()

jwks_t* r_jws_get_jwks_pubkey | ( | jws_t * | jws | ) |

Get public keys set for the verification

Parameters

  jws | the jws_t to get the value

Returns
  the public key set in jwks_t * format

## ◆ r_jws_parse()

int r_jws_parse | ( | jws_t * | jws,
|  | const char * | jws_str,
|  | int | x5u_flags
| ) |  |

Parses the JWS, verify the signature if the JWS header contains the public key

Parameters

  jws | the jws_t to update
  jws_str | the jws 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_jws_parsen()

int r_jws_parsen | ( | jws_t * | jws,
|  | const char * | jws_str,
|  | size_t | jws_str_len,
|  | int | x5u_flags
| ) |  |

Parses the JWS, verify the signature if the JWS header contains the public key

Parameters

  jws | the jws_t to update
  jws_str | the jws serialized to parse
  jws_str_len | the length of jws_str to parse
  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_jws_verify_signature()

int r_jws_verify_signature | ( | jws_t * | jws,
|  | jwk_t * | jwk_pubkey,
|  | int | x5u_flags
| ) |  |

Verifies the signature of the JWS The JWS must contain a signature or the JWS must have alg: none

Parameters

  jws | the jws_t to update
  jwk_pubkey | the public key to check the signature, can be NULL if jws 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
  RHN_OK on success, an error value on error

## ◆ r_jws_serialize()

char* r_jws_serialize | ( | jws_t * | jws,
|  | jwk_t * | jwk_privkey,
|  | int | x5u_flags
| ) |  |

Serialize a JWS into its string format (xxx.yyy.zzz)

Parameters

  jws | the JWS to serialize
  jwk_privkey | the private key to use to sign the JWS can be NULL if jws 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
  the JWS in serialized format, returned value must be r_free'd after use