# Derivation
[OMXMLSecurity]

## Functions
AXIS2_EXTERN axis2_status_t | oxs_derivation_derive_key (const axutil_env_t *env, oxs_key_t *secret, oxs_key_t *derived_key, axis2_bool_t build_fresh)
AXIS2_EXTERN axiom_node_t * | oxs_derivation_build_derived_key_token (const axutil_env_t *env, oxs_key_t *derived_key, axiom_node_t *parent, axis2_char_t *stref_uri, axis2_char_t *stref_val_type, axis2_char_t *wsc_ns_uri)
AXIS2_EXTERN axiom_node_t * | oxs_derivation_build_derived_key_token_with_stre (const axutil_env_t *env, oxs_key_t *derived_key, axiom_node_t *parent, axiom_node_t *stre, axis2_char_t *wsc_ns_uri)
AXIS2_EXTERN oxs_key_t * | oxs_derivation_extract_derived_key_from_token (const axutil_env_t *env, axiom_node_t *dk_token, axiom_node_t *root_node, oxs_key_t *session_key)

## Function Documentation

AXIS2_EXTERN axiom_node_t* oxs_derivation_build_derived_key_token | ( | const axutil_env_t * | env,
|  | oxs_key_t * | derived_key,
|  | axiom_node_t * | parent,
|  | axis2_char_t * | stref_uri,
|  | axis2_char_t * | stref_val_type,
|  | axis2_char_t * | wsc_ns_uri |
| ) |  |  |

Build the <wsc:DerivedKeyToken> depending a given derived key The token will be attached to the parent

Parameters:

  | env | pointer to environment struct
  | derived_key | The derived key to be used to get information
  | parent | The parent node to be attached to
  | stref_uri | Security Token Reference URI
  | stref_val_type | Security Token Reference Valut Type
  | wsc_ns_uri | namespace uri of ws-secconv version

Returns:
  the built axiom node

AXIS2_EXTERN axiom_node_t* oxs_derivation_build_derived_key_token_with_stre | ( | const axutil_env_t * | env,
|  | oxs_key_t * | derived_key,
|  | axiom_node_t * | parent,
|  | axiom_node_t * | stre,
|  | axis2_char_t * | wsc_ns_uri |
| ) |  |  |

Build the <wsc:DerivedKeyToken> depending a given derived key The token will be attached to the parent

Parameters:

  | env | pointer to environment struct
  | derived_key | The derived key to be used to get information
  | parent | The parent node to be attached to
  | stre | Security Toekn Reference element
  | wsc_ns_uri | namespace uri of ws-secconv version

Returns:
  the built axiom node

AXIS2_EXTERN axis2_status_t oxs_derivation_derive_key | ( | const axutil_env_t * | env,
|  | oxs_key_t * | secret,
|  | oxs_key_t * | derived_key,
|  | axis2_bool_t | build_fresh |
| ) |  |  |

Derive Key depending on the secret key Caller must free memory for derived key

Parameters:

  | env | pointer to environment struct
  | secret | The secret is the shared secret that is exchanged (note that if two secrets were securely exchanged, possible as part of an initial exchange, they are concatenated in the order they were sent/received)
  | derived_key | The derived key. Caller must create and free
  | build_fresh | Whether to build fresh or build using details in derived key (in case of recovering the derive key from xml)

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN oxs_key_t* oxs_derivation_extract_derived_key_from_token | ( | const axutil_env_t * | env,
|  | axiom_node_t * | dk_token,
|  | axiom_node_t * | root_node,
|  | oxs_key_t * | session_key |
| ) |  |  |

Extract information from an AXIOM node of typ <wsse:DerivedKeyToken> and build a key If the (optional) session_key is NULL then extract it form the refered EncryptedKey. Otherwise use it to Derive a new key using information available in the dk_token.

Parameters:

  | env | pointer to environment struct
  | dk_token | The <wsse:DerivedKeyToken> axiom node
  | root_node | The root node, which the search scope limited to
  | session_key | The session key, which is the base for the key derivation.
  | return | the derived key on SUCCESS or NULL on failure