The STM API which encapsulates an STS. More...
Typedefs | |
typedef struct _ato_Stm | ato_Stm |
The STM object used to interact with an STS service to retrieve Security Tokens (ato_StmTkn). | |
Functions | |
ATO_STM_EXPORT int | ato_stm_create (ato_Ctx *ctx, ato_Stm **stm, const char *stsurl, const char *stmtemplate) |
Create an STM object from the XML stored in stmtemplate. More... | |
ATO_STM_EXPORT void | ato_stm_free (ato_Ctx *ctx, ato_Stm *stm) |
Free the STM object. More... | |
ATO_STM_EXPORT int | ato_stm_set_template_vars (ato_Ctx *ctx, ato_Stm *stm, const char *const *vars) |
If the template loaded by ato_stm_create() contains "variables", update them with runtime values. More... | |
ATO_STM_EXPORT int | ato_stm_set_template_varstr (ato_Ctx *ctx, ato_Stm *stm, const char *varstr) |
Same as ato_stm_set_template_vars() except use a comma delimited string. More... | |
ATO_STM_EXPORT void | ato_stm_purgecache (ato_Ctx *ctx, bool purgeall) |
Purge the STM token cache for the current context/thread. More... | |
ATO_STM_EXPORT void | ato_stm_setexpiryinterval (ato_Stm *stm, size_t expirymins) |
Set the expiry interval (mins) for requested SecurityTokens at time of request - see also ato_stmtkm_isexpired() and ato_stmtkn_expirytime(). More... | |
ATO_STM_EXPORT size_t | ato_stm_expiryinterval (ato_Stm *stm) |
The current expiry time interval in minutes - see also ato_stm_setexpiryinterval() More... | |
ATO_STM_EXPORT int | ato_stm_stsissue (ato_Ctx *ctx, ato_Stm *stm, ato_StmTkn **st, ato_String *certificate, ato_String *privatekey, const char *relyingpartyurl) |
Submit an STS issue request to the STS service and return a SecurityToken response object. More... | |
ATO_STM_EXPORT int | ato_stm_loadst (ato_Ctx *ctx, ato_Stm *stm, ato_StmTkn **st, ato_String *atorstr) |
Deserialise a SecurityToken (ST) based on the contents of a previously serialised ST. More... | |
ATO_STM_EXPORT size_t | ato_stm_timeout (ato_Ctx *ctx, ato_Stm *stm) |
Get the network total timeout value, in seconds, used for requests to Vanguard STS. More... | |
ATO_STM_EXPORT void | ato_stm_settimeout (ato_Ctx *ctx, ato_Stm *stm, size_t timeout) |
Set the network total timeout value, in seconds, used for requests to Vanguard STS. More... | |
ATO_STM_EXPORT size_t | ato_stm_timeoutconnect (ato_Ctx *ctx, ato_Stm *stm) |
Get the network connect timeout value, in seconds, used for requests to Vanguard STS. More... | |
ATO_STM_EXPORT void | ato_stm_settimeoutconnect (ato_Ctx *ctx, ato_Stm *stm, size_t timeout) |
Set the network connect timeout value, in seconds, used for requests to Vanguard STS. More... | |
The STM API which encapsulates an STS.
ATO_STM_EXPORT int ato_stm_create | ( | ato_Ctx * | ctx, |
ato_Stm ** | stm, | ||
const char * | stsurl, | ||
const char * | stmtemplate | ||
) |
Create an STM object from the XML stored in stmtemplate.
ctx | the current thread local Context. |
stm | the address of the object to create. |
stsurl | the URL of the STS service to use. If NULL, the value is read from the current configuration. |
stmtemplate | the XML content. |
Free the STM object.
ctx | the current thread local Context. |
stm | the STM object. If NULL do nothing. |
ATO_STM_EXPORT int ato_stm_set_template_vars | ( | ato_Ctx * | ctx, |
ato_Stm * | stm, | ||
const char *const * | vars | ||
) |
If the template loaded by ato_stm_create() contains "variables", update them with runtime values.
Variable names in the template are defined by @{varname}. The varname (without the @{}) is used in the vars list.
The template itself as loaded by ato_stm_create() is not affected.
If this is called multiple times, it accumulates names/values in an internal list. If a name already exists, it's value is replaced. To clear the list, use NULL. Any NULL names/values are ignored. Otherwise it is expected to be a list of pairs of variable name1, variable value1, ... Variable names that do not exist or where the value is NULL, are ignored.
The name must match exactly (case-sensitive) what is in the template and must be <= 50 chars.
The last call determines the values used for subsequent calls to ato_stm_stsissue().
ctx | the current thread local Context. |
stm | the STM object. |
vars | an array of name1, value1, name2, value2, ... If NULL clear the existing list. |
ATO_STM_EXPORT int ato_stm_set_template_varstr | ( | ato_Ctx * | ctx, |
ato_Stm * | stm, | ||
const char * | varstr | ||
) |
Same as ato_stm_set_template_vars() except use a comma delimited string.
ctx | the current thread local Context. |
stm | the STM object. |
varstr | a string of comma delimited chars e.g. name1,value1,name2,value2, ... If NULL clear the existing list. |
ATO_STM_EXPORT void ato_stm_purgecache | ( | ato_Ctx * | ctx, |
bool | purgeall | ||
) |
Purge the STM token cache for the current context/thread.
ctx | the current thread local Context. |
purgeall | if TRUE remove all tokens, otherwise remove only stale (expired) tokens. |
ATO_STM_EXPORT void ato_stm_setexpiryinterval | ( | ato_Stm * | stm, |
size_t | expirymins | ||
) |
Set the expiry interval (mins) for requested SecurityTokens at time of request - see also ato_stmtkm_isexpired() and ato_stmtkn_expirytime().
This is applied to all subsequent requests. if not explicitly set, the default is 5 minutes. The allowed ranged is 5 to 30 mins. If less than 5 mins is specified, then 5 mins is set; if greater than 30 mins is specified, then 30 mins is set.
stm | the STM object. |
expirymins | the number of minutes from the request time that the SecurityToken should remain valid. |
ATO_STM_EXPORT size_t ato_stm_expiryinterval | ( | ato_Stm * | stm | ) |
The current expiry time interval in minutes - see also ato_stm_setexpiryinterval()
This is applied to requests (ato_stm_stsissue()). The SecurityToken is set to expired at the time of the request + specified number of minutes.
stm | the STM object. |
ATO_STM_EXPORT int ato_stm_stsissue | ( | ato_Ctx * | ctx, |
ato_Stm * | stm, | ||
ato_StmTkn ** | st, | ||
ato_String * | certificate, | ||
ato_String * | privatekey, | ||
const char * | relyingpartyurl | ||
) |
Submit an STS issue request to the STS service and return a SecurityToken response object.
The Security Token expiry time is set to a default value unless set using ato_stm_setexpirytime(). If the SecurityToken already exists int the cache and is not expired, then this is used instead, and no call is made to the STS service.
ctx | the current thread local Context. |
stm | the STM object. |
st | the SecurityToken object address (do not free) or NULL if none or an error occurred. |
certificate | X509 certificate. |
privatekey | P8 private key. |
relyingpartyurl | the relying party for which the token is issued. |
ATO_STM_EXPORT int ato_stm_loadst | ( | ato_Ctx * | ctx, |
ato_Stm * | stm, | ||
ato_StmTkn ** | st, | ||
ato_String * | atorstr | ||
) |
Deserialise a SecurityToken (ST) based on the contents of a previously serialised ST.
This creates a corresponding ST object in the ST cache. An error results if the ST already exists in the cache. However, expired STs are accepted, so check ato_stmtkn_isexpired() before using the ST.
ctx | the current thread local Context. |
stm | the STM object. |
st | the SecurityToken object address (do not free) or NULL if none or an error occurred. |
atorstr | Serialised ST content which includes the RSTR and stkey. |
Get the network total timeout value, in seconds, used for requests to Vanguard STS.
ctx | the current thread local Context. |
stm | the STM object. |
Set the network total timeout value, in seconds, used for requests to Vanguard STS.
ctx | the current thread local Context. |
stm | the STM object. |
timeout | the timeout value to set. |
Get the network connect timeout value, in seconds, used for requests to Vanguard STS.
ctx | the current thread local Context. |
stm | the STM object. |