pkcs11-helper
Files | Classes | Typedefs | Functions
Certificate interface

Files

file  pkcs11h-certificate.h
 pkcs11-helper certificate functions.
 

Classes

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

Typedefs

typedef struct pkcs11h_certificate_id_spkcs11h_certificate_id_t
 Certificate id reference.
 
typedef struct pkcs11h_certificate_s * pkcs11h_certificate_t
 Certificate object.
 
typedef struct pkcs11h_certificate_id_list_spkcs11h_certificate_id_list_t
 Certificate id list.
 

Functions

CK_RV pkcs11h_certificate_freeCertificateId (IN pkcs11h_certificate_id_t certificate_id)
 Free certificate_id object. More...
 
CK_RV pkcs11h_certificate_duplicateCertificateId (OUT pkcs11h_certificate_id_t *const to, IN const pkcs11h_certificate_id_t from)
 Duplicate certificate_id object. More...
 
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. More...
 
CK_RV pkcs11h_certificate_freeCertificate (IN pkcs11h_certificate_t certificate)
 Free certificate object. More...
 
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. More...
 
unsigned pkcs11h_certificate_getPromptMask (IN const pkcs11h_certificate_t certificate)
 Extract user data out of certificate. More...
 
void pkcs11h_certificate_setPromptMask (IN const pkcs11h_certificate_t certificate, IN const unsigned mask_prompt)
 Extract user data out of certificate. More...
 
void * pkcs11h_certificate_getUserData (IN const pkcs11h_certificate_t certificate)
 Extract user data out of certificate. More...
 
void pkcs11h_certificate_setUserData (IN const pkcs11h_certificate_t certificate, IN void *const user_data)
 Extract user data out of certificate. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
CK_RV pkcs11h_certificate_ensureCertificateAccess (IN const pkcs11h_certificate_t certificate)
 Ensure certificate is accessible. More...
 
CK_RV pkcs11h_certificate_ensureKeyAccess (IN const pkcs11h_certificate_t certificate)
 Ensure key is accessible. More...
 
CK_RV pkcs11h_certificate_lockSession (IN const pkcs11h_certificate_t certificate)
 Lock session for threded environment. More...
 
CK_RV pkcs11h_certificate_releaseSession (IN const pkcs11h_certificate_t certificate)
 Releases session lock. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
CK_RV pkcs11h_certificate_freeCertificateIdList (IN const pkcs11h_certificate_id_list_t cert_id_list)
 Free certificate_id list. More...
 
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. More...
 
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. More...
 

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