pkcs11-helper
Classes | Files | Typedefs | Functions

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_idCertificate id object to be based on.
user_dataOptional user data, to be passed to hooks.
mask_promptAllow prompt PKCS11H_PROMPT_MASK.
pin_cache_periodSession specific cache period.
p_certificateReceives 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:
certificateCertificate object.
mech_typePKCS#11 mechanism.
sourceBuffer to sign.
source_sizeBuffer size.
targetTarget buffer.
p_target_sizeTarget 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:
certificateCertificate object.
mech_typePKCS#11 mechanism.
sourceBuffer to sign.
source_sizeBuffer size.
targetTarget buffer.
p_target_sizeTarget 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_idid.
szInut 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:
toTarget.
fromSource.
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:
certificateCertificate object.
Returns:
CK_RV.
CK_RV pkcs11h_certificate_ensureKeyAccess ( IN const pkcs11h_certificate_t  certificate)

Ensure key is accessible.

Parameters:
certificateCertificate 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:
methodHow to fetch certificates PKCS11H_ENUM_METHOD.
user_dataSome user specific data.
mask_promptAllow prompt PKCS11H_PROMPT_MASK.
p_cert_id_issuers_listReceives issues list.
p_cert_id_end_listReceives 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_idToken id to enum.
methodHow to fetch certificates PKCS11H_ENUM_METHOD.
user_dataSome user specific data.
mask_promptAllow prompt PKCS11H_PROMPT_MASK.
p_cert_id_issuers_listReceives issues list.
p_cert_id_end_listReceives 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:
certificateCertificate 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_idCertificate 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_listList.
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:
certificateCertificate object.
certificate_blobBuffer.
p_certificate_blob_sizeBuffer 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:
certificateCertificate object.
p_certificate_idCertificate 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:
certificateCertificate object.
Returns:
Mask prompt PKCS11H_PROMPT_MASK.
void* pkcs11h_certificate_getUserData ( IN const pkcs11h_certificate_t  certificate)

Extract user data out of certificate.

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

Lock session for threded environment.

Parameters:
certificateCertificate 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:
certificateCertificate 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:
szOutput string.
maxMax buffer size.
certificate_idid 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_idCertificate id object.
blobCertificate blob.
blob_sizeCertificate 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:
certificateCertificate object.
mask_promptAllow 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:
certificateCertificate object.
user_dataOptional 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:
certificateCertificate object.
mech_typePKCS#11 mechanism.
sourceBuffer to sign.
source_sizeBuffer size.
targetTarget buffer.
p_target_sizeTarget 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:
certificateCertificate object.
mech_typePKCS#11 mechanism.
sourceBuffer to sign.
source_sizeBuffer size.
targetTarget buffer.
p_target_sizeTarget 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:
certificateCertificate object.
mech_typePKCS#11 mechanism.
sourceBuffer to sign.
source_sizeBuffer size.
targetTarget buffer.
p_target_sizeTarget 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:
certificateCertificate object.
mech_typePKCS#11 mechanism.
sourceBuffer to sign.
source_sizeBuffer size.
targetTarget buffer.
p_target_sizeTarget 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