Go to the first, previous, next, last section, table of contents.

6 Cryptsh

The cryptsh programm offers the ability to access a PKCS#11 implementation via an interactive programm. The Cryptsh is based on the guile scheme interpreter and all function pertaining the use of the PKCS#11 Module are implemented as scheme functions.

All functions return a pair of the cryptoki return code and the output parameters relevant to the function. The later are detailed in the descriptions of each function. The former is not mentioned when decribing the return values of each function, rather outlining only the cdr of the pair.

Currently the following functions return only the return code, which I consider a bug and will fix it asap: C-Initialize

The version structures returned by some functions are mapped into a pair.

6.1 General-Purpose Functions

The GetFunctionList funtion is not supported by the cryptsh as it is called internally when the cryptsh is started.

Function: C-Initialize
Initialize the PKCS#11 Module.

Since the function pointers that are provided to the equivalent C function for setting the threading methods are not availiable in scheme, these cannot be set by the funcion.

Function: C-Finalize
shut down connection to PKCS#11 module.

Function: C-GetInfo
Return information about the PKCS#11 module.

The return value of the function will contain the contents of a CK_INFO structure as a list in the cdr: version of the cryptoki interface, manufacturer ID padded with blanks to a lengh of 32 characters, the flags, the library description (also blank padded), and library version.

6.2 Slot and Token Management Functions

Function: C-GetSlotList tokenp
Return the list of valid slot ID's. If tokenp is set to #t only slots that contain tokens are returned, otherwise all slots are listed.

Function: C-GetSlotInfo slot_int
Return information about a slot as list holding the elements of the CK_SLOT_INFO structure. The elements are as follows: slot description, manufacturerID, flags, hardware version, firmware version (for details check section 10.5 of the PKCS#11 standard document)

Function: C-GetTokenInfo slot_int
Return information about a token occupying the slot with the given slot ID. A list containing the elements of the CK_TOKEN_INFO structure are returned:
a string padded with blanks to a lenght of 32 characters
a string padded with blanks to a lenght of 32 characters
a string padded with blanks to a lenght of 16 characters
a string padded with blanks to a lenght of 16 characters
An integer number from following or'ed values:
CKF_RNG token has its own random generator
CKF_WRITE_PROTECTED token is write-protected
CKF_LOGIN_REQUIRED user must login in order to use R/W functions.
CKF_USER_PIN_INITIALIZED normal user's PIN is set
a string padded with blanks to a lenght of 16 characters.

More details on the semantics of each of the elements are described in section 8.2 of the PKCS#11 standard document.

Function: C-WaitForSlotEvent flags_ulong
Function will wait for an event on a Slot to occour. The function will block further execution if the flags value is set to zero and will continue execution even if no event ocoured if the value is 1.

Function: C-GetMechanismList slot_ulong
the function returns a list of the mechanism identifiers as defined in the pkcs11t.h

Function: C-GetMechanismInfo slot_ulong mech_type_ulong
Function returns a list of the elements of the CK_MECHANISM_INFO structure: minimum lenght of key, maximum length of key,

mechanism is performed in software extensions. Must be FALSE for this version
Bit Flag Mask Meaning
CKF_HW 0x00000001 TRUE if the mechanism is performed by the device; FALSE if the
CKF_ENCRYPT 0x00000100 TRUE if the mechanism can be used with C_EncryptInit
CKF_DECRYPT 0x00000200 TRUE if the mechanism can be used with C_DecryptInit
CKF_DIGEST 0x00000400 TRUE if the mechanism can be used with C_DigestInit
CKF_SIGN 0x00000800 TRUE if the mechanism can be used with C_SignInit
CKF_SIGN_RECOVER 0x00001000 TRUE if the mechanism can be used with C_SignRecoverInit
CKF_VERIFY 0x00002000 TRUE if the mechanism can be used with C_VerifyInit
CKF_VERIFY_RECOVER 0x00004000 TRUE if the mechanism can be used with C_VerifyRecoverInit
CKF_GENERATE 0x00008000 TRUE if the mechanism can be used with C_GenerateKey
CKF_GENERATE_KEY_PAIR 0x00010000 TRUE if the mechanism can be used with C_GenerateKeyPair
CKF_WRAP 0x00020000 TRUE if the mechanism can be used with C_WrapKey
CKF_UNWRAP 0x00040000 TRUE if the mechanism can be used with C_UnwrapKey
CKF_DERIVE 0x00080000 TRUE if the mechanism can be used with C_DeriveKey
CKF_EXTENSION 0x80000000 TRUE if there is an extension to the flags; FALSE if no

Function: C-InitToken slot_ulong pin_string label_string
(Re-)Set the token with a new pin and label. The strings may be any sequence of bytes, but this may lead to problems in other applications.

Function: C-InitPin session_ulong pin_string

Function: C-SetPin session_ulong oldpin_string newpin_string

6.3 Session Management Functions

Function: C-OpenSession slot_ulong flags_ulong
Returns the session handle

Function: C-CloseSession handle_ulong

Function: C-CloseAllSessions slot_ulong

Function: C-GetSessionInfo session_ulong

Function: C-GetOperationState session_ulong null_data

Function: C-SetOperationState session state enc_key auth_key

Function: C-Login session_ulong user_ulong pin_string

Function: C-Logout session_ulong

6.4 Object Management Function

Function: C-CreateObject session_ulong attribs_list

Function: C-CopyObject session_ulong object_ulong template_list

Function: C-DestroyObject session_ulong object_ulong

Function: C-GetObjectSize session_ulong object_ulong

Function: C-GetAttributeValue session_ulong object_ulong attr_list
The attr-list must contain the list of attribute type IDs that function shall look up. The function returns a pair of the error code and a list of lists of two elements each. Each of these tuples contains one attribute type ID and its corresponding value.

Function: C-SetAttributeValue session_ulong object_ulong template_list
template_list must contain a list of list of two elements eacht. These tuples each contain the attribute type ID and its value.

Function: C-FindObjectsInit session_ulong attribs_list

Function: C-FindObjects session_ulong

Function: C-FindObjectsFinal session_ulong

6.5 Encryption Functions

Function: C-EncryptInit session_ulong mechanism_list key_ulong

Function: C-Encrypt session_ulong data_string null_data

Function: C-EncryptUpdate session_ulong data_string null_data

Function: C-EncryptFinal session_ulong null_data

6.6 Decryption Functions

Function: C-DecryptInit session_ulong mechanism_list key_ulong

Function: C-Decrypt session_ulong data_string null_data

Function: C-DecryptUpdate session_ulong data_string null_data

Function: C-DecryptFinal session_ulong null_data

6.7 Message Digesting Functions

Function: C-DigestInit session_ulong mechanism_list

Function: C-Digest session_ulong data_string null_data

Function: C-DigestUpdate session_ulong data_string

Function: C-DigestKey session_ulong key_ulong

Function: C-DigestFinal session_ulong null_data

6.8 Signing MACing Functions

Function: C-SignInit session_ulong mechanism_list key_ulong

Function: C-Sign session_ulong data_string null_data

Function: C-SignUpdate session_ulong data_string

Function: C-SignFinal session_ulong null_data

Function: C-SignRecoverInit session_ulong mechanism_list key_ulong

Function: C-SignRecover session_ulong data_string null_data

6.9 Functions for Verifying Signatures and MACs

Function: C-VerifyInit session_ulong mechanism_list key_ulong

Function: C-Verify session data_string signature_string

Function: C-VerifyUpdate session_ulong part_string

Function: C-VerifyFinal session_ulong signature_string

Function: C-VerifyRecoverInit session_ulong mechanism_list key_ulong

Function: C-VerifyRecover session_ulong signature_string null_data

6.10 Dual-Function Cryptographics

Function: C-DigestEncryptUpdate session part null_data

Function: C-DecryptDigestUpdate session enc_part null_data

Function: C-SignEncryptUpdate session part null_data

Function: C-DecryptVerifyUpdate session enc_part null_data

6.11 Key Manamgement Functions

Function: C-GenerateKey session mechanism template
generate a new key. session is the session handle for the session to be used, mechanism a list of values in the order of definition as given for the mechanism structure. template is a list of pairs that give default values for attributes of the object to be created.

The function returns a pair of the the value returned by the PKCS#11 C function and the handle of the key that was created. If the return value is not CKR_OK (0) the handle of the key is set to 0.

Function: C-GenerateKeyPair session mechanism public_template private_template
generate a new pair of private and public key. session provides the handle of the session that this pair is created in, mechanism states the mechanism to be used. For valid mechanism please check with the standard. public_template and private_template are lists of pairs that give default values for attributes for the public and private key respectively.

The function returns a pair of the value returned by the PKCS#11 C function and a pair of the public and the private key.

Function: C-WrapKey session mech_list wrapper wrappeenull_data

Function: C-UnwrapKey session mechanism unwrapper wrapped template

Function: C-DeriveKey session mechanism base_key template

6.12 Random Number Generation Functions

Function: C-SeedRandom session_ulong seed_string

Function: C-GenerateRandom session_ulong len_ulong

6.13 Parallel functions Management Functions

Function: C-GetFunctionStatus session

Function: C-CancelFunction session

6.14 Helper Functions

These functions aid in handling certificates or require the use of an ASN.1 Parser. They call code in the OpenSSL library more or less directly.

Function: create-cert-req session key subject file
create a new certificate. Function PEM encodes the data and writes it to a file. The filename is given as the last parameter.

Go to the first, previous, next, last section, table of contents.