atoakm  3.2.0
ATOMAS atoakm
Credential

Retrieve information from credentials. More...

Typedefs

typedef struct _ato_Credential ato_Credential
 The credential object. More...
 

Enumerations

enum  ato_eCredtype { ATO_NONE , ATO_CREDUSER , ATO_CREDDEVICE }
 Defines the type of credential. More...
 
enum  ato_eCredfilter {
  ATO_FILTER_ALL , ATO_FILTER_VALID , ATO_FILTER_USER , ATO_FILTER_VALIDUSER ,
  ATO_FILTER_DEVICE , ATO_FILTER_VALIDDEVICE
}
 Used to filter lists of ato_Credential in a keystore - see ato_ks_credentials(). More...
 

Functions

ATO_AKM_EXPORT const char * ato_cr_id (ato_Credential *cr)
 Return the credential id. More...
 
ATO_AKM_EXPORT const char * ato_cr_alias (ato_Credential *cr)
 Same as ato_cr_id(). More...
 
ATO_AKM_EXPORT ato_eCredtype ato_cr_type (ato_Credential *cr)
 Return the credential type. More...
 
ATO_AKM_EXPORT const char * ato_cr_abn (ato_Credential *cr)
 Return the credential ABN. More...
 
ATO_AKM_EXPORT const char * ato_cr_legalname (ato_Credential *cr)
 Return the credential legal name. More...
 
ATO_AKM_EXPORT const char * ato_cr_serialnr (ato_Credential *cr)
 Return the credential serial number. More...
 
ATO_AKM_EXPORT const char * ato_cr_creationdate (ato_Credential *cr)
 Return the credential creation time. More...
 
ATO_AKM_EXPORT const char * ato_cr_notbefore (ato_Credential *cr)
 Returns the start of the credential validity period. More...
 
ATO_AKM_EXPORT const char * ato_cr_notafter (ato_Credential *cr)
 Returns the end of the credential validity period. More...
 
ATO_AKM_EXPORT const char * ato_cr_sha1fingerprint (ato_Credential *cr)
 Return the credential SHA1 fingerprint. More...
 
ATO_AKM_EXPORT const char * ato_cr_sha1fingerprint_hex (ato_Ctx *ctx, ato_Credential *cr)
 Return the credential SHA1 fingerprint as a hex string. More...
 
ATO_AKM_EXPORT const char * ato_cr_personid (ato_Credential *cr)
 Return the credential person id or NULL if not a USER credential. More...
 
ATO_AKM_EXPORT const char * ato_cr_devicename (ato_Credential *cr)
 Return the credential device name or NULL if not a DEVICE credential. More...
 
ATO_AKM_EXPORT const char * ato_cr_givenames (ato_Credential *cr)
 Return the credential given name(s) or NULL if not a USER credential. More...
 
ATO_AKM_EXPORT const char * ato_cr_familyname (ato_Credential *cr)
 Return the credential family name or NULL if not a USER credential. More...
 
ATO_AKM_EXPORT bool ato_cr_matchesfilter (ato_Credential *cr, ato_eCredfilter filter)
 Determines if the credential matches the given filter criteria. More...
 
ATO_AKM_EXPORT bool ato_cr_iscurrent (ato_Credential *cr)
 Determines if the credential is current (between NotBefore and NotAfter dates). More...
 
ATO_AKM_EXPORT bool ato_cr_ismodified (ato_Credential *cr)
 Check if the credential has been changed since the last load. More...
 
ATO_AKM_EXPORT bool ato_cr_isrenewed (ato_Credential *cr)
 Determines if the credential is renewed, this relates only to the current session. More...
 
ATO_AKM_EXPORT bool ato_cr_isrenewable (ato_Ctx *ctx, ato_Credential *cr)
 Determines if the credential is ready to be renewed - see ato_cr_renew(). More...
 
ATO_AKM_EXPORT bool ato_is_integrity_valid (ato_Ctx *ctx, ato_Credential *cr)
 Determines if the credential matches its expected integrity value. More...
 
ATO_AKM_EXPORT int ato_cr_checkcorrectpwd (ato_Ctx *ctx, ato_Credential *cr, const char *pwd)
 Test if the password is correct for the credential. More...
 
ATO_AKM_EXPORT int ato_cr_iscorrectpwd (ato_Ctx *ctx, ato_Credential *cr, bool *correct, const char *pwd)
 
ATO_AKM_EXPORT bool ato_cr_ispbe2 (ato_Ctx *ctx, ato_Credential *cr)
 Determines if the credential P8 uses PBES1 or PBES2 scheme. More...
 
ATO_AKM_EXPORT int ato_cr_certificate (ato_Ctx *ctx, ato_Credential *cr, ato_String **certificate)
 Construct a X509 certificate object from the credential and return as a DER encoded array. More...
 
ATO_AKM_EXPORT int ato_cr_chain (ato_Ctx *ctx, ato_Credential *cr, ato_String **certificates)
 Construct a P7 certificate chain object from the credential and return as a DER encoded array. More...
 
ATO_AKM_EXPORT int ato_cr_privatekey (ato_Ctx *ctx, ato_Credential *cr, ato_String **privatekey, const char *pwd)
 Construct a decrypted private key object from the credential and return as a DER encoded array. More...
 
ATO_AKM_EXPORT int ato_cr_p12 (ato_Ctx *ctx, ato_Credential *cr, ato_String **p12, const char *pwd)
 Construct a P12 object from the credential and return as a DER encoded array. More...
 
ATO_AKM_EXPORT ato_Stringato_cr_integrityvalue (ato_Credential *cr)
 Return the integrityvalue stored in the keystore for the credential. More...
 
ATO_AKM_EXPORT ato_Stringato_cr_b64salt (ato_Credential *cr)
 Return the salt stored in the keystore for the credential. More...
 
ATO_AKM_EXPORT ato_Stringato_cr_b64p7 (ato_Credential *cr)
 Return the base64 encoded P7c stored in the keystore for the credential. More...
 
ATO_AKM_EXPORT ato_Stringato_cr_b64p8 (ato_Credential *cr)
 Return the base64 encoded P8 stored in the keystore for the credential. More...
 
ATO_AKM_EXPORT int ato_cr_sign (ato_Ctx *ctx, ato_Credential *cr, ato_String **signed_data, const char *pwd, const char *data, size_t len)
 Sign some data using the private key. More...
 
ATO_AKM_EXPORT int ato_cr_request_generate (ato_Ctx *ctx, ato_Credential *cr, const char *pwd, const char *id)
 Credential request. More...
 
ATO_AKM_EXPORT ato_Stringato_cr_b64p10 (ato_Credential *cr)
 Returns the p10 request. More...
 
ATO_AKM_EXPORT ato_Stringato_cr_request_data (ato_Credential *cr)
 Return the data generated from ato_cr_request_generate(). More...
 
ATO_AKM_EXPORT int ato_cr_request_process (ato_Ctx *ctx, ato_Credential *cr, const char *responseData)
 Credential request. More...
 

Detailed Description

Retrieve information from credentials.

Typedef Documentation

◆ ato_Credential

typedef struct _ato_Credential ato_Credential

The credential object.

An credential has a limited lifetime defined by ato_cr_notbefore() and ato_cr_notafter().

Enumeration Type Documentation

◆ ato_eCredtype

Defines the type of credential.

Enumerator
ATO_NONE 

Credential type is undefined.

ATO_CREDUSER 

User Credential.

ATO_CREDDEVICE 

Device Credential.

◆ ato_eCredfilter

Used to filter lists of ato_Credential in a keystore - see ato_ks_credentials().

Enumerator
ATO_FILTER_ALL 

Include all credential records.

ATO_FILTER_VALID 

Include credentials which are currently valid.

See ato_cr_isvalid()

ATO_FILTER_USER 

Include user credentials only.

ATO_FILTER_VALIDUSER 

Include user credentials which are valid.

ATO_FILTER_DEVICE 

Include device credentials only.

ATO_FILTER_VALIDDEVICE 

Include device credentials which are valid.

Function Documentation

◆ ato_cr_id()

ATO_AKM_EXPORT const char* ato_cr_id ( ato_Credential cr)

Return the credential id.

This corresponds to the credential "id" attributed in the store.

Parameters
crthe credential object.
Returns
id.

◆ ato_cr_alias()

ATO_AKM_EXPORT const char* ato_cr_alias ( ato_Credential cr)

Same as ato_cr_id().

Parameters
crthe credential object.
Returns
id.

◆ ato_cr_type()

ATO_AKM_EXPORT ato_eCredtype ato_cr_type ( ato_Credential cr)

Return the credential type.

Parameters
crthe credential object.
Returns
credential type.

◆ ato_cr_abn()

ATO_AKM_EXPORT const char* ato_cr_abn ( ato_Credential cr)

Return the credential ABN.

Parameters
crthe credential object.
Returns
credential ABN.

◆ ato_cr_legalname()

ATO_AKM_EXPORT const char* ato_cr_legalname ( ato_Credential cr)

Return the credential legal name.

Parameters
crthe credential object.
Returns
credential legal name.

◆ ato_cr_serialnr()

ATO_AKM_EXPORT const char* ato_cr_serialnr ( ato_Credential cr)

Return the credential serial number.

Parameters
crthe credential object.
Returns
credential serial number.

◆ ato_cr_creationdate()

ATO_AKM_EXPORT const char* ato_cr_creationdate ( ato_Credential cr)

Return the credential creation time.

Parameters
crthe credential object.
Returns
credential creation timestamp.

◆ ato_cr_notbefore()

ATO_AKM_EXPORT const char* ato_cr_notbefore ( ato_Credential cr)

Returns the start of the credential validity period.

Parameters
crthe credential object.
Returns
timestamp when credential is first valid.

◆ ato_cr_notafter()

ATO_AKM_EXPORT const char* ato_cr_notafter ( ato_Credential cr)

Returns the end of the credential validity period.

Parameters
crthe credential object.
Returns
timestamp when credential is last valid.

◆ ato_cr_sha1fingerprint()

ATO_AKM_EXPORT const char* ato_cr_sha1fingerprint ( ato_Credential cr)

Return the credential SHA1 fingerprint.

Parameters
crthe credential object.
Returns
SHA1 fingerprint as base64.

◆ ato_cr_sha1fingerprint_hex()

ATO_AKM_EXPORT const char* ato_cr_sha1fingerprint_hex ( ato_Ctx ctx,
ato_Credential cr 
)

Return the credential SHA1 fingerprint as a hex string.

Parameters
ctxthe current thread local Context
crthe credential object.
Returns
SHA1 fingerprint as hex.

◆ ato_cr_personid()

ATO_AKM_EXPORT const char* ato_cr_personid ( ato_Credential cr)

Return the credential person id or NULL if not a USER credential.

Parameters
crthe credential object.
Returns
Family name.

◆ ato_cr_devicename()

ATO_AKM_EXPORT const char* ato_cr_devicename ( ato_Credential cr)

Return the credential device name or NULL if not a DEVICE credential.

Parameters
crthe credential object.
Returns
Family name.

◆ ato_cr_givenames()

ATO_AKM_EXPORT const char* ato_cr_givenames ( ato_Credential cr)

Return the credential given name(s) or NULL if not a USER credential.

Parameters
crthe credential object.
Returns
Family name.

◆ ato_cr_familyname()

ATO_AKM_EXPORT const char* ato_cr_familyname ( ato_Credential cr)

Return the credential family name or NULL if not a USER credential.

Parameters
crthe credential object.
Returns
Family name.

◆ ato_cr_matchesfilter()

ATO_AKM_EXPORT bool ato_cr_matchesfilter ( ato_Credential cr,
ato_eCredfilter  filter 
)

Determines if the credential matches the given filter criteria.

Parameters
crthe credential object.
filterthe filter to check.
Returns
TRUE or FALSE.

◆ ato_cr_iscurrent()

ATO_AKM_EXPORT bool ato_cr_iscurrent ( ato_Credential cr)

Determines if the credential is current (between NotBefore and NotAfter dates).

Parameters
crthe credential object.
Returns
TRUE or FALSE.

◆ ato_cr_ismodified()

ATO_AKM_EXPORT bool ato_cr_ismodified ( ato_Credential cr)

Check if the credential has been changed since the last load.

Parameters
crthe credential object.
Returns
TRUE or FALSE.

◆ ato_cr_isrenewed()

ATO_AKM_EXPORT bool ato_cr_isrenewed ( ato_Credential cr)

Determines if the credential is renewed, this relates only to the current session.

Parameters
crthe credential object.
Returns
TRUE or FALSE.

◆ ato_cr_isrenewable()

ATO_AKM_EXPORT bool ato_cr_isrenewable ( ato_Ctx ctx,
ato_Credential cr 
)

Determines if the credential is ready to be renewed - see ato_cr_renew().

Prior to using a method that access a credential private key, ato_cr_renew() or ato_cr_isrenewable() MUST be called at least once per session, for the given credential, otherwise the method in questions will return the error ATO_AKM_ERR_RENEWNOTCALLED.

To effectively disable renewal, simply call this method and not ato_cr_renew().

If the credential is due to expire within 14 months it is within the expiry period. This expiry period can be set in the config file, although the minimum is 14 months. A 25 month period for a 2 year credential will result in a new credential always being renewed - useful for testing.

Parameters
ctxthe current thread local Context
crthe credential object.
Returns
TRUE if it is not currently renewed, is valid, and is within the expiry period.

◆ ato_is_integrity_valid()

ATO_AKM_EXPORT bool ato_is_integrity_valid ( ato_Ctx ctx,
ato_Credential cr 
)

Determines if the credential matches its expected integrity value.

This will always be true, unless the credential has changed or, possibly if the keystore was loaded without integrity validation and there is a mismatch. Used for testing scenarious.

Parameters
ctxthe current thread local Context
crthe credential object.
Returns
TRUE if valid; FALSE otherwise or if an internal exception has occurred.

◆ ato_cr_checkcorrectpwd()

ATO_AKM_EXPORT int ato_cr_checkcorrectpwd ( ato_Ctx ctx,
ato_Credential cr,
const char *  pwd 
)

Test if the password is correct for the credential.

Parameters
ctxthe current thread local Context.
crthe credential object.
pwdthe password
Returns
ATO_ERR_OK(0) if successful, otherwise
  • ATO_AKM_ERR_PWD if the password is wrong For any other error, also check for the presence of a nested inner error.

◆ ato_cr_iscorrectpwd()

ATO_AKM_EXPORT int ato_cr_iscorrectpwd ( ato_Ctx ctx,
ato_Credential cr,
bool *  correct,
const char *  pwd 
)
Deprecated:
{ Use ato_cr_checkcorrectpwd().

}

Determines if the credential password is valid.

Given that all credentials in a keystore must have the same password, this is really just a convenience method on the credential.

Parameters
ctxthe current thread local Context
crthe credential object.
correctaddress of the bool/int to set as TRUE or FALSE
pwdthe password to test
Returns
ATO_ERR_OK, else an error code if an internal exception has occured

◆ ato_cr_ispbe2()

ATO_AKM_EXPORT bool ato_cr_ispbe2 ( ato_Ctx ctx,
ato_Credential cr 
)

Determines if the credential P8 uses PBES1 or PBES2 scheme.

Parameters
ctxthe current thread local Context
crthe credential object.
Returns
TRUE if PBES2

◆ ato_cr_certificate()

ATO_AKM_EXPORT int ato_cr_certificate ( ato_Ctx ctx,
ato_Credential cr,
ato_String **  certificate 
)

Construct a X509 certificate object from the credential and return as a DER encoded array.

This includes the principle as well as the issuer certificates.

Parameters
ctxthe current thread local Context
crthe credential object.
certificatethe address of an ato_String object to allocate. The caller must free this using ato_str_free().
Returns
ATO_ERR_OK(0) if successful, otherwise
  • ?

◆ ato_cr_chain()

ATO_AKM_EXPORT int ato_cr_chain ( ato_Ctx ctx,
ato_Credential cr,
ato_String **  certificates 
)

Construct a P7 certificate chain object from the credential and return as a DER encoded array.

This includes the principle as well as the issuer certificates.

Parameters
ctxthe current thread local Context.
crthe credential object.
certificatesthe address of an ato_String object to allocate. The caller must free this using ato_str_free().
Returns
ATO_ERR_OK(0) if successful, otherwise
  • ?

◆ ato_cr_privatekey()

ATO_AKM_EXPORT int ato_cr_privatekey ( ato_Ctx ctx,
ato_Credential cr,
ato_String **  privatekey,
const char *  pwd 
)

Construct a decrypted private key object from the credential and return as a DER encoded array.

Parameters
ctxthe current thread local Context.
crthe credential object.
privatekeythe address of an ato_String object to allocate. The caller must free this using ato_str_free().
pwdthe password used to access the private key.
Returns
ATO_ERR_OK(0) if successful, otherwise
  • ATO_AKM_ERR_BADPWD if the password is wrong
  • ATO_AKM_ERR_RENEWNOTCALLED if ato_cr_renew() or ato_cr_isrenewable() has not been called

◆ ato_cr_p12()

ATO_AKM_EXPORT int ato_cr_p12 ( ato_Ctx ctx,
ato_Credential cr,
ato_String **  p12,
const char *  pwd 
)

Construct a P12 object from the credential and return as a DER encoded array.

Parameters
ctxthe current thread local Context.
crthe credential object.
p12the address of an ato_String object to allocate. The caller must free this using ato_str_free().
pwdthe password used to access the private key.
Returns
ATO_ERR_OK(0) if successful, otherwise
  • ATO_AKM_ERR_BADPWD if the password is wrong
  • ATO_AKM_ERR_RENEWNOTCALLED if ato_cr_renew() or ato_cr_isrenewable() has not been called

◆ ato_cr_integrityvalue()

ATO_AKM_EXPORT ato_String* ato_cr_integrityvalue ( ato_Credential cr)

Return the integrityvalue stored in the keystore for the credential.

Parameters
crthe credential object.
Returns
An ato_String object containing the data, which is null terminated.

◆ ato_cr_b64salt()

ATO_AKM_EXPORT ato_String* ato_cr_b64salt ( ato_Credential cr)

Return the salt stored in the keystore for the credential.

Parameters
crthe credential object.
Returns
An ato_String object containing the data, which is null terminated.

◆ ato_cr_b64p7()

ATO_AKM_EXPORT ato_String* ato_cr_b64p7 ( ato_Credential cr)

Return the base64 encoded P7c stored in the keystore for the credential.

Parameters
crthe credential object.
Returns
An ato_String object containing the data, which is null terminated.

◆ ato_cr_b64p8()

ATO_AKM_EXPORT ato_String* ato_cr_b64p8 ( ato_Credential cr)

Return the base64 encoded P8 stored in the keystore for the credential.

Parameters
crthe credential object.
Returns
An ato_String object containing the data, which is null terminated.

◆ ato_cr_sign()

ATO_AKM_EXPORT int ato_cr_sign ( ato_Ctx ctx,
ato_Credential cr,
ato_String **  signed_data,
const char *  pwd,
const char *  data,
size_t  len 
)

Sign some data using the private key.

Parameters
ctxthe current thread local Context.
crthe credential object.
signed_datathe address of an ato_String object to allocate. The caller must free this using ato_str_free().
pwdthe password used to access the private key.
datathe data to sign.
lenthe length of data.
Returns
ATO_ERR_OK(0) if successful, otherwise
  • ATO_AKM_ERR_BADPWD if the password is wrong

◆ ato_cr_request_generate()

ATO_AKM_EXPORT int ato_cr_request_generate ( ato_Ctx ctx,
ato_Credential cr,
const char *  pwd,
const char *  id 
)

Credential request.

Parameters
ctxthe current thread local Context.
crthe credential object.
pwdthe password used to access the private key.
idused to match request/response - should be unique.
Returns
ATO_ERR_OK(0) if successful, otherwise
  • ATO_AKM_ERR_NOTRENEWABLE if credential cannot be "renewed"
  • ATO_AKM_ERR_BADPWD if the password is wrong
  • other

◆ ato_cr_b64p10()

ATO_AKM_EXPORT ato_String* ato_cr_b64p10 ( ato_Credential cr)

Returns the p10 request.

Parameters
crthe credential object.
Returns
request data.

◆ ato_cr_request_data()

ATO_AKM_EXPORT ato_String* ato_cr_request_data ( ato_Credential cr)

Return the data generated from ato_cr_request_generate().

Parameters
crthe credential object.
Returns
request data.

◆ ato_cr_request_process()

ATO_AKM_EXPORT int ato_cr_request_process ( ato_Ctx ctx,
ato_Credential cr,
const char *  responseData 
)

Credential request.

Parameters
ctxthe current thread local Context.
crthe credential object.
responseDatathe response from the service.
Returns
ATO_ERR_OK(0) if successful