atoakm  3.2.0
ATOMAS atoakm
Keystore

Load keystores and retrieving credentials. More...

Typedefs

typedef struct _ato_Keystore ato_Keystore
 The keystore object.
 

Functions

ATO_AKM_EXPORT int ato_ks_create (ato_Ctx *ctx, ato_Keystore **ks, const char *buffer, const ato_ksProperties *properties)
 Create a keystore object from the XML stored in buffer. More...
 
ATO_AKM_EXPORT void * ato_ks_free (ato_Keystore *ks)
 Free the keystore object if not NULL. More...
 
ATO_AKM_EXPORT ato_ksPropertiesato_ks_properties (ato_Keystore *ks)
 get the properties object associated with the keystore. More...
 
ATO_AKM_EXPORT bool ato_ks_ismodified (ato_Keystore *ks)
 Returns TRUE if the keystore or any of its credentials has been modified since the last created or loaded. More...
 
ATO_AKM_EXPORT bool ato_ks_isvalid (ato_Keystore *ks)
 Returns FALSE if the keystore is in invalid state due to a failed update operation. More...
 
ATO_AKM_EXPORT int ato_ks_save (ato_Ctx *ctx, ato_Keystore *ks, char **buffer)
 Save the keystore to a buffer. More...
 
ATO_AKM_EXPORT size_t ato_ks_count (ato_Keystore *ks, ato_eCredfilter filter)
 Return the number of credentials in the keystore matching the filter ato_eCredfilter. More...
 
ATO_AKM_EXPORT ato_Credentialato_ks_credential (ato_Keystore *ks, const char *alias)
 Return the credential corresponding to alias or NULL if not found. More...
 
ATO_AKM_EXPORT size_t ato_ks_credentials (ato_Keystore *ks, ato_Credential ***creds, ato_eCredfilter filter)
 Return an allocated array of credentials according to the filter provided. More...
 
ATO_AKM_EXPORT size_t ato_ks_delete (ato_Keystore *ks, const char *alias)
 Delete the credential corresponding to the alias or all credentials if alias is NULL. More...
 
ATO_AKM_EXPORT int ato_ks_checkcorrectpwd (ato_Ctx *ctx, ato_Keystore *ks, const char *pwd)
 Test if the password is correct without accessing any particular credential. More...
 
ATO_AKM_EXPORT int ato_ks_iscorrectpwd (ato_Ctx *ctx, ato_Keystore *ks, bool *correct, const char *pwd)
 
ATO_AKM_EXPORT int ato_ks_changepwd (ato_Ctx *ctx, ato_Keystore *ks, const char *pwd, const char *newpwd)
 Change the password for all credentials in the keystore - see ato_ks_pwdpolicy_desc() for password rules. More...
 
ATO_AKM_EXPORT bool ato_ks_pwdpolicy_isvalid (ato_Keystore *ks, const char *pwd)
 Check if the password matches the password policy - see ato_ks_pwdpolicy_desc(). More...
 
ATO_AKM_EXPORT const char * ato_ks_pwdpolicy_desc (ato_Keystore *ks)
 Return the password policy as a string. More...
 
ATO_AKM_EXPORT int ato_ks_addcredential (ato_Ctx *ctx, ato_Keystore *ks, const char *pwd, ato_Credential *cr, const char *crpwd, bool isreplacable)
 Add a credential from another keystore to a destination keystore - replaces ato_ks_copycredential. More...
 

Detailed Description

Load keystores and retrieving credentials.

Function Documentation

◆ ato_ks_create()

ATO_AKM_EXPORT int ato_ks_create ( ato_Ctx ctx,
ato_Keystore **  ks,
const char *  buffer,
const ato_ksProperties properties 
)

Create a keystore object from the XML stored in buffer.

Parameters
ctxthe current thread local Context.
ksthe address of the object to create. *obj must be initialised to NULL.
bufferthe XML content. If null, an empty keystore is created.
propertiesoptional properties to use for the keystore. An internal copy of this is created, which means that ato_ks_properties() will return the internal copy.
Returns
ATO_ERR_OK

◆ ato_ks_free()

ATO_AKM_EXPORT void* ato_ks_free ( ato_Keystore ks)

Free the keystore object if not NULL.

Parameters
ksthe keystore object. If NULL do nothing.
Returns
NULL

◆ ato_ks_properties()

ATO_AKM_EXPORT ato_ksProperties* ato_ks_properties ( ato_Keystore ks)

get the properties object associated with the keystore.

Parameters
ksthe keystore object.
Returns
the properties object associated with the keystore.

◆ ato_ks_ismodified()

ATO_AKM_EXPORT bool ato_ks_ismodified ( ato_Keystore ks)

Returns TRUE if the keystore or any of its credentials has been modified since the last created or loaded.

Parameters
ksthe keystore object.
Returns
TRUE or FALSE

◆ ato_ks_isvalid()

ATO_AKM_EXPORT bool ato_ks_isvalid ( ato_Keystore ks)

Returns FALSE if the keystore is in invalid state due to a failed update operation.

This may occur if a change password works for some credentials but not others. If this occurs, the in-memory keystore should be discarded and reloaded.

Parameters
ksthe keystore object.
Returns
TRUE or FALSE

◆ ato_ks_save()

ATO_AKM_EXPORT int ato_ks_save ( ato_Ctx ctx,
ato_Keystore ks,
char **  buffer 
)

Save the keystore to a buffer.

This does not change the internal state meaning that ismodified() will still be true.

Parameters
ctxthe current thread local Context.
ksthe keystore object.
bufferthe buffer to allocate. This caller must free this using ato_str_free().
Returns
ATO_ERR_OK if successful, otherwise
  • ATO_AKM_ERR_KEYSTORE_CORRUPTED where the keystore should be discarded and reloaded.

◆ ato_ks_count()

ATO_AKM_EXPORT size_t ato_ks_count ( ato_Keystore ks,
ato_eCredfilter  filter 
)

Return the number of credentials in the keystore matching the filter ato_eCredfilter.

Parameters
ksthe keystore object.
filterthe filter to use - ATO_FILTER_ALL counts all records.
Returns
number of credentials.

◆ ato_ks_credential()

ATO_AKM_EXPORT ato_Credential* ato_ks_credential ( ato_Keystore ks,
const char *  alias 
)

Return the credential corresponding to alias or NULL if not found.

Parameters
ksthe keystore object.
aliasthe alias (i.e. xml id) for the credential.
Returns
the credential or NULL if the alias is not found.

◆ ato_ks_credentials()

ATO_AKM_EXPORT size_t ato_ks_credentials ( ato_Keystore ks,
ato_Credential ***  creds,
ato_eCredfilter  filter 
)

Return an allocated array of credentials according to the filter provided.

This is in the original order.

Parameters
ksthe keystore object.
credsthe variable to allocate an array of credentials to. This must be freed by the caller. Do not, however, free the credentials themselves, as they will be freed when the ato_ks_free() is called.
filterthe type of credential to include.
Returns
the size of the array.

◆ ato_ks_delete()

ATO_AKM_EXPORT size_t ato_ks_delete ( ato_Keystore ks,
const char *  alias 
)

Delete the credential corresponding to the alias or all credentials if alias is NULL.

Parameters
ksthe keystore object.
aliasthe alias (i.e. xml id) for the credential. If NULL, delete all credentials.
Returns
ATO_ERR_OK if successful

◆ ato_ks_checkcorrectpwd()

ATO_AKM_EXPORT int ato_ks_checkcorrectpwd ( ato_Ctx ctx,
ato_Keystore ks,
const char *  pwd 
)

Test if the password is correct without accessing any particular credential.

Parameters
ctxthe current thread local Context.
ksthe keystore object.
pwdthe password
Returns
ATO_ERR_OK(0) if successful, otherwise
  • ATO_AKM_ERR_PWD if the password is wrong
  • ATO_AKM_ERR_PWDPOLICY if the keystore is empty and the password doesn't meet strength requirements For any other error, also check for the presence of a nested inner error.

◆ ato_ks_iscorrectpwd()

ATO_AKM_EXPORT int ato_ks_iscorrectpwd ( ato_Ctx ctx,
ato_Keystore ks,
bool *  correct,
const char *  pwd 
)
Deprecated:
{ Use ato_ks_checkcorrectpwd().

}

Test if the password is correct without accessing any particular credential.

If the keystore is empty this will be true if it matches the password policy.

Parameters
ctxthe current thread local Context.
ksthe keystore object.
correctthe address of the boolean to set to TRUE or FALSE
pwdthe password
Returns
ATO_ERR_OK or an errcode.

◆ ato_ks_changepwd()

ATO_AKM_EXPORT int ato_ks_changepwd ( ato_Ctx ctx,
ato_Keystore ks,
const char *  pwd,
const char *  newpwd 
)

Change the password for all credentials in the keystore - see ato_ks_pwdpolicy_desc() for password rules.

If multi-threading, ensure that the keystore is not involved in any current ato_ks_copycredential operation.

Parameters
ctxthe current thread local Context.
ksthe keystore
pwdthe password
newpwdthe new password
Returns
ATO_ERR_OK(0) if successful, otherwise
  • ATO_AKM_ERR_PWD if the password is wrong
  • ATO_AKM_ERR_PWDPOLICY if the new password doesn't meet strength requirements
  • ATO_AKM_ERR_GENERAL for any other error. For any error, a nested inner error, if any, will contain more details.

◆ ato_ks_pwdpolicy_isvalid()

ATO_AKM_EXPORT bool ato_ks_pwdpolicy_isvalid ( ato_Keystore ks,
const char *  pwd 
)

Check if the password matches the password policy - see ato_ks_pwdpolicy_desc().

It is possible this may vary in future versions of the keystore.

Parameters
ksthe keystore. If NULL, the latest policy is used.
pwdthe password
Returns
TRUE or FALSE.

◆ ato_ks_pwdpolicy_desc()

ATO_AKM_EXPORT const char* ato_ks_pwdpolicy_desc ( ato_Keystore ks)

Return the password policy as a string.

Currently a password must contain:

  • no whitespace
  • at least 1 uppercase character
  • at least 1 lowercase character
  • at least 1 digit OR 1 punctuation character
  • at least 10 printable characters
Parameters
ksthe keystore. If NULL, the latest policy description (above) is returned.
Returns
The above content as a string - including embedded newlines.

◆ ato_ks_addcredential()

ATO_AKM_EXPORT int ato_ks_addcredential ( ato_Ctx ctx,
ato_Keystore ks,
const char *  pwd,
ato_Credential cr,
const char *  crpwd,
bool  isreplacable 
)

Add a credential from another keystore to a destination keystore - replaces ato_ks_copycredential.

If multi-threading, ensure that either keystores are not involved in any ato_ks_changepwd operation.

Parameters
ctxthe current thread local Context.
ksthe keystore.
pwdthe password of the keystore.
crthe credential to add to the keystore.
crpwdthe password of the credential (source keystore); can be NULL if same as destination keystore.
isreplacableused if the alias already exists in the dstks. If TRUE then replace it,
Returns
ATO_ERR_OK(0) if successful, otherwise
  • ATO_AKM_ERR_CREDNOTFOUND if the credential does not exist in the source store
  • ATO_AKM_ERR_ALIASEXISTS if isreplacable is FALSE and credential alias already exists in the destination store
  • ATO_AKM_ERR_BADPWD if the source credential password is wrong
  • ATO_AKM_ERR_PWDDEST if the destination store password is wrong
  • ATO_AKM_ERR_PWDPOLICY if this is a new password that doesn't meet strength requirements
  • ATO_AKM_ERR_COPYCREDENTIAL if a general error occured - see message text for details