Certificate interface

Classes

struct  pkcs11h_certificate_id_s
 Certificate id reference. More...
struct  pkcs11h_certificate_id_list_s
 Certificate id list. More...

Files

file  pkcs11h-certificate.h
 

pkcs11-helper certificate functions.


Typedefs

typedef struct
pkcs11h_certificate_id_s
pkcs11h_certificate_id_t
 Certificate id reference.
typedef struct
pkcs11h_certificate_s * 
pkcs11h_certificate_t
 Certificate object.
typedef struct
pkcs11h_certificate_id_list_s
pkcs11h_certificate_id_list_t
 Certificate id list.

Functions

CK_RV pkcs11h_certificate_freeCertificateId (IN pkcs11h_certificate_id_t certificate_id)
 Free certificate_id object.
CK_RV pkcs11h_certificate_duplicateCertificateId (OUT pkcs11h_certificate_id_t *const to, IN const pkcs11h_certificate_id_t from)
 Duplicate certificate_id object.
CK_RV pkcs11h_certificate_setCertificateIdCertificateBlob (IN const pkcs11h_certificate_id_t certificate_id, IN const unsigned char *const blob, IN const size_t blob_size)
 Sets internal certificate_id blob.
CK_RV pkcs11h_certificate_freeCertificate (IN pkcs11h_certificate_t certificate)
 Free certificate object.
CK_RV pkcs11h_certificate_create (IN const pkcs11h_certificate_id_t certificate_id, IN void *const user_data, IN const unsigned mask_prompt, IN const int pin_cache_period, OUT pkcs11h_certificate_t *const p_certificate)
 Create a certificate object out of certificate_id.
unsigned pkcs11h_certificate_getPromptMask (IN const pkcs11h_certificate_t certificate)
 Extract user data out of certificate.
void pkcs11h_certificate_setPromptMask (IN const pkcs11h_certificate_t certificate, IN const unsigned mask_prompt)
 Extract user data out of certificate.
void * pkcs11h_certificate_getUserData (IN const pkcs11h_certificate_t certificate)
 Extract user data out of certificate.
void pkcs11h_certificate_setUserData (IN const pkcs11h_certificate_t certificate, IN void *const user_data)
 Extract user data out of certificate.
CK_RV pkcs11h_certificate_getCertificateId (IN const pkcs11h_certificate_t certificate, OUT pkcs11h_certificate_id_t *const p_certificate_id)
 Get certifiate id object out of a certifiate.
CK_RV pkcs11h_certificate_getCertificateBlob (IN const pkcs11h_certificate_t certificate, OUT unsigned char *const certificate_blob, IN OUT size_t *const p_certificate_blob_size)
 Get the certificate blob out of the certificate object.
CK_RV pkcs11h_certificate_serializeCertificateId (OUT char *const sz, IN OUT size_t *max, IN const pkcs11h_certificate_id_t certificate_id)
 Serialize certificate_id into a string.
CK_RV pkcs11h_certificate_deserializeCertificateId (OUT pkcs11h_certificate_id_t *const p_certificate_id, IN const char *const sz)
 Deserialize certificate_id out of string.
CK_RV pkcs11h_certificate_ensureCertificateAccess (IN const pkcs11h_certificate_t certificate)
 Ensure certificate is accessible.
CK_RV pkcs11h_certificate_ensureKeyAccess (IN const pkcs11h_certificate_t certificate)
 Ensure key is accessible.
CK_RV pkcs11h_certificate_lockSession (IN const pkcs11h_certificate_t certificate)
 Lock session for threded environment.
CK_RV pkcs11h_certificate_releaseSession (IN const pkcs11h_certificate_t certificate)
 Releases session lock.
CK_RV pkcs11h_certificate_sign (IN const pkcs11h_certificate_t certificate, IN const CK_MECHANISM_TYPE mech_type, IN const unsigned char *const source, IN const size_t source_size, OUT unsigned char *const target, IN OUT size_t *const p_target_size)
 Sign data.
CK_RV pkcs11h_certificate_signRecover (IN const pkcs11h_certificate_t certificate, IN const CK_MECHANISM_TYPE mech_type, IN const unsigned char *const source, IN const size_t source_size, OUT unsigned char *const target, IN OUT size_t *const p_target_size)
 Sign data.
CK_RV pkcs11h_certificate_decrypt (IN const pkcs11h_certificate_t certificate, IN const CK_MECHANISM_TYPE mech_type, IN const unsigned char *const source, IN const size_t source_size, OUT unsigned char *const target, IN OUT size_t *const p_target_size)
 Decrypt data.
CK_RV pkcs11h_certificate_unwrap (IN const pkcs11h_certificate_t certificate, IN const CK_MECHANISM_TYPE mech_type, IN const unsigned char *const source, IN const size_t source_size, OUT unsigned char *const target, IN OUT size_t *const p_target_size)
 Decrypt data.
CK_RV pkcs11h_certificate_signAny (IN const pkcs11h_certificate_t certificate, IN const CK_MECHANISM_TYPE mech_type, IN const unsigned char *const source, IN const size_t source_size, OUT unsigned char *const target, IN OUT size_t *const p_target_size)
 Sign data mechanism determined by key attributes.
CK_RV pkcs11h_certificate_decryptAny (IN const pkcs11h_certificate_t certificate, IN const CK_MECHANISM_TYPE mech_type, IN const unsigned char *const source, IN const size_t source_size, OUT unsigned char *const target, IN OUT size_t *const p_target_size)
 Decrypt data mechanism determined by key attributes.
CK_RV pkcs11h_certificate_freeCertificateIdList (IN const pkcs11h_certificate_id_list_t cert_id_list)
 Free certificate_id list.
CK_RV pkcs11h_certificate_enumTokenCertificateIds (IN const pkcs11h_token_id_t token_id, IN const unsigned method, IN void *const user_data, IN const unsigned mask_prompt, OUT pkcs11h_certificate_id_list_t *const p_cert_id_issuers_list, OUT pkcs11h_certificate_id_list_t *const p_cert_id_end_list)
 Enumerate available certificates on specific token.
CK_RV pkcs11h_certificate_enumCertificateIds (IN const unsigned method, IN void *const user_data, IN const unsigned mask_prompt, OUT pkcs11h_certificate_id_list_t *const p_cert_id_issuers_list, OUT pkcs11h_certificate_id_list_t *const p_cert_id_end_list)
 Enumerate available certificates.

Detailed Description

X.509 certificate interface, provides signature and decryption.


Function Documentation

CK_RV pkcs11h_certificate_create ( IN const pkcs11h_certificate_id_t  certificate_id,
IN void *const   user_data,
IN const unsigned  mask_prompt,
IN const int  pin_cache_period,
OUT pkcs11h_certificate_t *const   p_certificate 
)

Create a certificate object out of certificate_id.

Parameters:
certificate_id Certificate id object to be based on.
user_data Optional user data, to be passed to hooks.
mask_prompt Allow prompt PKCS11H_PROMPT_MASK.
pin_cache_period Session specific cache period.
p_certificate Receives certificate object.
Note:
Caller must free result.
See also:
pkcs11h_certificate_freeCertificate().
Remarks:
The certificate id object may not specify the certificate blob.
Examples:
test-certificate.c.
CK_RV pkcs11h_certificate_decrypt ( IN const pkcs11h_certificate_t  certificate,
IN const CK_MECHANISM_TYPE  mech_type,
IN const unsigned char *const   source,
IN const size_t  source_size,
OUT unsigned char *const   target,
IN OUT size_t *const   p_target_size 
)

Decrypt data.

Parameters:
certificate Certificate object.
mech_type PKCS#11 mechanism.
source Buffer to sign.
source_size Buffer size.
target Target buffer.
p_target_size Target buffer size.
Returns:
CK_RV.
Note:
target may be NULL to get size.
Attention:
When using in threaded environment session must be locked.
See also:
pkcs11h_certificate_lockSession().
CK_RV pkcs11h_certificate_decryptAny ( IN const pkcs11h_certificate_t  certificate,
IN const CK_MECHANISM_TYPE  mech_type,
IN const unsigned char *const   source,
IN const size_t  source_size,
OUT unsigned char *const   target,
IN OUT size_t *const   p_target_size 
)

Decrypt data mechanism determined by key attributes.

Parameters:
certificate Certificate object.
mech_type PKCS#11 mechanism.
source Buffer to sign.
source_size Buffer size.
target Target buffer.
p_target_size Target buffer size.
Returns:
CK_RV.
Note:
target may be NULL to get size.
Attention:
When using in threaded environment session must be locked.
See also:
pkcs11h_certificate_lockSession().
CK_RV pkcs11h_certificate_deserializeCertificateId ( OUT pkcs11h_certificate_id_t *const   p_certificate_id,
IN const char *const   sz 
)

Deserialize certificate_id out of string.

Parameters:
p_certificate_id id.
sz Inut string
Returns:
CK_RV.
Note:
Caller must free result.
See also:
pkcs11h_certificate_freeCertificateId().
CK_RV pkcs11h_certificate_duplicateCertificateId ( OUT pkcs11h_certificate_id_t *const   to,
IN const pkcs11h_certificate_id_t  from 
)

Duplicate certificate_id object.

Parameters:
to Target.
from Source.
Returns:
CK_RV.
Note:
Caller must free result.
See also:
pkcs11h_certificate_freeCertificateId().
CK_RV pkcs11h_certificate_ensureCertificateAccess ( IN const pkcs11h_certificate_t  certificate  ) 

Ensure certificate is accessible.

Parameters:
certificate Certificate object.
Returns:
CK_RV.
CK_RV pkcs11h_certificate_ensureKeyAccess ( IN const pkcs11h_certificate_t  certificate  ) 

Ensure key is accessible.

Parameters:
certificate Certificate object.
Returns:
CK_RV.
CK_RV pkcs11h_certificate_enumCertificateIds ( IN const unsigned  method,
IN void *const   user_data,
IN const unsigned  mask_prompt,
OUT pkcs11h_certificate_id_list_t *const   p_cert_id_issuers_list,
OUT pkcs11h_certificate_id_list_t *const   p_cert_id_end_list 
)

Enumerate available certificates.

Parameters:
method How to fetch certificates PKCS11H_ENUM_METHOD.
user_data Some user specific data.
mask_prompt Allow prompt PKCS11H_PROMPT_MASK.
p_cert_id_issuers_list Receives issues list.
p_cert_id_end_list Receives end certificates list.
Note:
p_cert_id_issuers_list may be NULL.
Caller must free result.
This function will likely take long time.
See also:
pkcs11h_certificate_freeCertificateIdList().
Examples:
test-certificate.c.
CK_RV pkcs11h_certificate_enumTokenCertificateIds ( IN const pkcs11h_token_id_t  token_id,
IN const unsigned  method,
IN void *const   user_data,
IN const unsigned  mask_prompt,
OUT pkcs11h_certificate_id_list_t *const   p_cert_id_issuers_list,
OUT pkcs11h_certificate_id_list_t *const   p_cert_id_end_list 
)

Enumerate available certificates on specific token.

Parameters:
token_id Token id to enum.
method How to fetch certificates PKCS11H_ENUM_METHOD.
user_data Some user specific data.
mask_prompt Allow prompt PKCS11H_PROMPT_MASK.
p_cert_id_issuers_list Receives issues list.
p_cert_id_end_list Receives end certificates list.
Returns:
CK_RV.
Note:
p_cert_id_issuers_list may be NULL.
Caller must free result.
This function will likely take long time.
See also:
pkcs11h_certificate_freeCertificateIdList().
CK_RV pkcs11h_certificate_freeCertificate ( IN pkcs11h_certificate_t  certificate  ) 

Free certificate object.

Parameters:
certificate Certificate object.
Returns:
CK_RV.
Examples:
test-certificate.c.
CK_RV pkcs11h_certificate_freeCertificateId ( IN pkcs11h_certificate_id_t  certificate_id  ) 

Free certificate_id object.

Parameters:
certificate_id Certificate id.
Returns:
CK_RV.
CK_RV pkcs11h_certificate_freeCertificateIdList ( IN const pkcs11h_certificate_id_list_t  cert_id_list  ) 

Free certificate_id list.

Parameters:
cert_id_list List.
Returns:
CK_RV.
Examples:
test-certificate.c.
CK_RV pkcs11h_certificate_getCertificateBlob ( IN const pkcs11h_certificate_t  certificate,
OUT unsigned char *const   certificate_blob,
IN OUT size_t *const   p_certificate_blob_size 
)

Get the certificate blob out of the certificate object.

Parameters:
certificate Certificate object.
certificate_blob Buffer.
p_certificate_blob_size Buffer size.
Returns:
CK_RV.
Note:
certificate_blob may be NULL in order to get size.
CK_RV pkcs11h_certificate_getCertificateId ( IN const pkcs11h_certificate_t  certificate,
OUT pkcs11h_certificate_id_t *const   p_certificate_id 
)

Get certifiate id object out of a certifiate.

Parameters:
certificate Certificate object.
p_certificate_id Certificate id object pointer.
Returns:
CK_RV.
Note:
Caller must free result.
See also:
pkcs11h_certificate_freeCertificateId().
unsigned pkcs11h_certificate_getPromptMask ( IN const pkcs11h_certificate_t  certificate  ) 

Extract user data out of certificate.

Parameters:
certificate Certificate object.
Returns:
Mask prompt PKCS11H_PROMPT_MASK.
void* pkcs11h_certificate_getUserData ( IN const pkcs11h_certificate_t  certificate  ) 

Extract user data out of certificate.

Parameters:
certificate Certificate object.
Returns:
User data.
CK_RV pkcs11h_certificate_lockSession ( IN const pkcs11h_certificate_t  certificate  ) 

Lock session for threded environment.

Parameters:
certificate Certificate object.
Returns:
CK_RV.
Remarks:
This must be called on threaded environment, so both calls to _sign and _signRecover and _decrypt will be from the same source. Failing to lock session, will result with CKR_OPERATION_ACTIVE if provider is good, or unexpected behaviour for others.
It is save to call this also in none threaded environment, it will do nothing. Call this also if you are doing one stage operation, since locking is not done by method.
CK_RV pkcs11h_certificate_releaseSession ( IN const pkcs11h_certificate_t  certificate  ) 

Releases session lock.

Parameters:
certificate Certificate object.
Returns:
CK_RV.
See also:
pkcs11h_certificate_lockSession().
CK_RV pkcs11h_certificate_serializeCertificateId ( OUT char *const   sz,
IN OUT size_t *  max,
IN const pkcs11h_certificate_id_t  certificate_id 
)

Serialize certificate_id into a string.

Parameters:
sz Output string.
max Max buffer size.
certificate_id id to serialize
Returns:
CK_RV.
Note:
sz may be NULL in order to get size.
CK_RV pkcs11h_certificate_setCertificateIdCertificateBlob ( IN const pkcs11h_certificate_id_t  certificate_id,
IN const unsigned char *const   blob,
IN const size_t  blob_size 
)

Sets internal certificate_id blob.

Parameters:
certificate_id Certificate id object.
blob Certificate blob.
blob_size Certificate blob size.
Returns:
CK_RV.
Remarks:
Useful to set after deserialization so certificate is available and not read from token.
void pkcs11h_certificate_setPromptMask ( IN const pkcs11h_certificate_t  certificate,
IN const unsigned  mask_prompt 
)

Extract user data out of certificate.

Parameters:
certificate Certificate object.
mask_prompt Allow prompt PKCS11H_PROMPT_MASK.
void pkcs11h_certificate_setUserData ( IN const pkcs11h_certificate_t  certificate,
IN void *const   user_data 
)

Extract user data out of certificate.

Parameters:
certificate Certificate object.
user_data Optional user data, to be passed to hooks.
CK_RV pkcs11h_certificate_sign ( IN const pkcs11h_certificate_t  certificate,
IN const CK_MECHANISM_TYPE  mech_type,
IN const unsigned char *const   source,
IN const size_t  source_size,
OUT unsigned char *const   target,
IN OUT size_t *const   p_target_size 
)

Sign data.

Parameters:
certificate Certificate object.
mech_type PKCS#11 mechanism.
source Buffer to sign.
source_size Buffer size.
target Target buffer.
p_target_size Target buffer size.
Returns:
CK_RV.
Note:
target may be NULL to get size.
Attention:
When using in threaded environment session must be locked.
See also:
pkcs11h_certificate_lockSession().
pkcs11h_certificate_signAny().
CK_RV pkcs11h_certificate_signAny ( IN const pkcs11h_certificate_t  certificate,
IN const CK_MECHANISM_TYPE  mech_type,
IN const unsigned char *const   source,
IN const size_t  source_size,
OUT unsigned char *const   target,
IN OUT size_t *const   p_target_size 
)

Sign data mechanism determined by key attributes.

Parameters:
certificate Certificate object.
mech_type PKCS#11 mechanism.
source Buffer to sign.
source_size Buffer size.
target Target buffer.
p_target_size Target buffer size.
Returns:
CK_RV.
Note:
target may be NULL to get size.
Attention:
When using in threaded environment session must be locked.
See also:
pkcs11h_certificate_lockSession().
Examples:
test-certificate.c.
CK_RV pkcs11h_certificate_signRecover ( IN const pkcs11h_certificate_t  certificate,
IN const CK_MECHANISM_TYPE  mech_type,
IN const unsigned char *const   source,
IN const size_t  source_size,
OUT unsigned char *const   target,
IN OUT size_t *const   p_target_size 
)

Sign data.

Parameters:
certificate Certificate object.
mech_type PKCS#11 mechanism.
source Buffer to sign.
source_size Buffer size.
target Target buffer.
p_target_size Target buffer size.
Returns:
CK_RV.
Note:
target may be NULL to get size.
Attention:
When using in threaded environment session must be locked.
See also:
pkcs11h_certificate_lockSession().
pkcs11h_certificate_signAny().
CK_RV pkcs11h_certificate_unwrap ( IN const pkcs11h_certificate_t  certificate,
IN const CK_MECHANISM_TYPE  mech_type,
IN const unsigned char *const   source,
IN const size_t  source_size,
OUT unsigned char *const   target,
IN OUT size_t *const   p_target_size 
)

Decrypt data.

Parameters:
certificate Certificate object.
mech_type PKCS#11 mechanism.
source Buffer to sign.
source_size Buffer size.
target Target buffer.
p_target_size Target buffer size.
Returns:
CK_RV.
Note:
target may be NULL to get size.
Attention:
When using in threaded environment session must be locked.
See also:
pkcs11h_certificate_lockSession().

pkcs11-helper, Copyright (C) Alon Bar-Lev <alon.barlev@gmail.com>OpenSC-Project.org Logo