atostm  3.2.0
ATOMAS atostm
STS Service

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...
 

Detailed Description

The STM API which encapsulates an STS.

Function Documentation

◆ ato_stm_create()

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.

Parameters
ctxthe current thread local Context.
stmthe address of the object to create.
stsurlthe URL of the STS service to use. If NULL, the value is read from the current configuration.
stmtemplatethe XML content.
Returns
ATO_ERR_OK or an errcode.

◆ ato_stm_free()

ATO_STM_EXPORT void ato_stm_free ( ato_Ctx ctx,
ato_Stm stm 
)

Free the STM object.

Parameters
ctxthe current thread local Context.
stmthe STM object. If NULL do nothing.

◆ ato_stm_set_template_vars()

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().

Parameters
ctxthe current thread local Context.
stmthe STM object.
varsan array of name1, value1, name2, value2, ... If NULL clear the existing list.
Returns
ATO_ERR_OK or an errcode.

◆ ato_stm_set_template_varstr()

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.

Parameters
ctxthe current thread local Context.
stmthe STM object.
varstra string of comma delimited chars e.g. name1,value1,name2,value2, ... If NULL clear the existing list.
Returns
ATO_ERR_OK or an errcode.

◆ ato_stm_purgecache()

ATO_STM_EXPORT void ato_stm_purgecache ( ato_Ctx ctx,
bool  purgeall 
)

Purge the STM token cache for the current context/thread.

Parameters
ctxthe current thread local Context.
purgeallif TRUE remove all tokens, otherwise remove only stale (expired) tokens.

◆ ato_stm_setexpiryinterval()

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.

Parameters
stmthe STM object.
expiryminsthe number of minutes from the request time that the SecurityToken should remain valid.

◆ ato_stm_expiryinterval()

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.

Parameters
stmthe STM object.
Returns
the number of minutes from the request time that the SecurityToken should remain valid.

◆ ato_stm_stsissue()

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.

Parameters
ctxthe current thread local Context.
stmthe STM object.
stthe SecurityToken object address (do not free) or NULL if none or an error occurred.
certificateX509 certificate.
privatekeyP8 private key.
relyingpartyurlthe relying party for which the token is issued.
Returns
ATO_ERR_OK or an errcode.

◆ ato_stm_loadst()

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.

Parameters
ctxthe current thread local Context.
stmthe STM object.
stthe SecurityToken object address (do not free) or NULL if none or an error occurred.
atorstrSerialised ST content which includes the RSTR and stkey.
Returns
ATO_ERR_OK or an errcode.

◆ ato_stm_timeout()

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.

Parameters
ctxthe current thread local Context.
stmthe STM object.
Returns
the current timeout value.

◆ ato_stm_settimeout()

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.

Parameters
ctxthe current thread local Context.
stmthe STM object.
timeoutthe timeout value to set.

◆ ato_stm_timeoutconnect()

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.

Parameters
ctxthe current thread local Context.
stmthe STM object.
Returns
the current timeout value.

◆ ato_stm_settimeoutconnect()

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.

Parameters
ctxthe current thread local Context.
stmthe STM object.
timeoutthe timeout value to set.