PKCS#11
|
| Cryptographic Token Interface Standard |
PKCS#11 |
Cryptoki provides the following functions for managing objects. Additional functions provided specifically for managing key objects are described in Section 11.14.
CK_RV C_CreateObject( CK_SESSION_HANDLE hSession, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount, CK_OBJECT_HANDLE_PTR phObject);
C_CreateObject creates a new object.
| hSession | is the session's handle; |
| pTemplate | points to the object's template; |
| ulCount | is the number of attributes in the template; |
| phObject | points to the location that receives the new object's handle. |
If C_CreateObject is used to create a key object, the key object will have its CKA_LOCAL attribute set to FALSE.
Only session objects can be created during a read-only session. Only public objects can be created unless the normal user is logged in.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hData, hCertificate, hKey; CK_OBJECT_CLASS dataClass = CKO_DATA, certificateClass = CKO_CERTIFICATE, keyClass = CKO_PUBLIC_KEY; CK_KEY_TYPE keyType = CKK_RSA; CK_CHAR application[] = {"My Application"}; CK_BYTE dataValue[] = {...}; CK_BYTE subject[] = {...}; CK_BYTE id[] = {...}; CK_BYTE certificateValue[] = {...}; CK_BYTE modulus[] = {...}; CK_BYTE exponent[] = {...}; CK_BYTE true = TRUE; CK_ATTRIBUTE dataTemplate[] = { {CKA_CLASS, &dataClass, sizeof(dataClass)}, {CKA_TOKEN, &true, sizeof(true)}, {CKA_APPLICATION, application, sizeof(application)}, {CKA_VALUE, dataValue, sizeof(dataValue)} }; CK_ATTRIBUTE certificateTemplate[] = { {CKA_CLASS, &certificateClass, sizeof(certificateClass)}, {CKA_TOKEN, &true, sizeof(true)}, {CKA_SUBJECT, subject, sizeof(subject)}, {CKA_ID, id, sizeof(id)}, {CKA_VALUE, certificateValue, sizeof(certificateValue)} }; CK_ATTRIBUTE keyTemplate[] = { {CKA_CLASS, &keyClass, sizeof(keyClass)}, {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, {CKA_WRAP, &true, sizeof(true)}, {CKA_MODULUS, modulus, sizeof(modulus)}, {CKA_PUBLIC_EXPONENT, exponent, sizeof(exponent)} }; CK_RV rv; . . . /* Create a data object */ rv = C_CreateObject(hSession, &dataTemplate, 4, &hData); if (rv == CKR_OK) { . . . } /* Create a certificate object */ rv = C_CreateObject( hSession, &certificateTemplate, 5, &hCertificate); if (rv == CKR_OK) { . . . } /* Create an RSA public key object */ rv = C_CreateObject(hSession, &keyTemplate, 5, &hKey); if (rv == CKR_OK) { . . . }
CK_RV C_CopyObject( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount, CK_OBJECT_HANDLE_PTR phNewObject);
C_CopyObject copies an object, creating a new object for the copy.
| hSession | is the session's handle; |
| hObject | is the object's handle; |
| pTemplate | points to the template for the new object; |
| ulCount | is the number of attributes in the template; |
| phNewObject | points to the location that receives the handle for the copy of the object. |
If a call to C_CopyObject cannot support the precise template supplied to it, it will fail and return without creating any object.
Only session objects can be created during a read-only session. Only public objects can be created unless the normal user is logged in.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hKey, hNewKey; CK_OBJECT_CLASS keyClass = CKO_SECRET_KEY; CK_KEY_TYPE keyType = CKK_DES; CK_BYTE id[] = {...}; CK_BYTE keyValue[] = {...}; CK_BYTE false = FALSE; CK_BYTE true = TRUE; CK_ATTRIBUTE keyTemplate[] = { {CKA_CLASS, &keyClass, sizeof(keyClass)}, {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, {CKA_TOKEN, &false, sizeof(false)}, {CKA_ID, id, sizeof(id)}, {CKA_VALUE, keyValue, sizeof(keyValue)} }; CK_ATTRIBUTE copyTemplate[] = { {CKA_TOKEN, &true, sizeof(true)} }; CK_RV rv; . . . /* Create a DES secret key session object */ rv = C_CreateObject(hSession, &keyTemplate, 5, &hKey); if (rv == CKR_OK) { /* Create a copy which is a token object */ rv = C_CopyObject(hSession, hKey, ©Template, 1, &hNewKey); . . . }
CK_RV C_DestroyObject( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject);
C_DestroyObject destroys an object.
| hSession | is the session's handle; |
| hObject | is the object's handle. |
CK_RV C_GetObjectSize( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_ULONG_PTR pulSize);
C_GetObjectSize gets the size of an object in bytes.
| hSession | is the session's handle; |
| hObject | is the object's handle; |
| pulSize | points to the location that receives the size in bytes of the object. |
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hObject; CK_OBJECT_CLASS dataClass = CKO_DATA; CK_CHAR application[] = {"My Application"}; CK_BYTE dataValue[] = {...}; CK_BYTE value[] = {...}; CK_BYTE true = TRUE; CK_ATTRIBUTE template[] = { {CKA_CLASS, &dataClass, sizeof(dataClass)}, {CKA_TOKEN, &true, sizeof(true)}, {CKA_APPLICATION, application, sizeof(application)}, {CKA_VALUE, value, sizeof(value)} }; CK_ULONG ulSize; CK_RV rv; . . . rv = C_CreateObject(hSession, &template, 4, &hObject); if (rv == CKR_OK) { rv = C_GetObjectSize(hSession, hObject, &ulSize); if (rv != CKR_INFORMATION_SENSITIVE) { . . . } rv = C_DestroyObject(hSession, hObject); . . . }
CK_RV C_GetAttributeValue( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount);
C_GetAttributeValue obtains the value of one or more attributes of an object.
| hSession | is the session's handle; |
| hObject | is the object's handle; |
| pTemplate | points to a template that specifies which attribute values are to be obtained, and receives the attribute values; |
| ulCount | is the number of attributes in the template. |
Note that the error codes CKR_ATTRIBUTE_SENSITIVE, CKR_ATTRIBUTE_TYPE_INVALID, and CKR_BUFFER_TOO_SMALL do not denote true errors for C_GetAttributeValue. If a call to C_GetAttributeValue returns any of these three values, then the call must nonetheless have processed every attribute in the template supplied to C_GetAttributeValue. Each attribute in the template whose value can be returned by the call to C_GetAttributeValue will be returned by the call to C_GetAttributeValue.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hObject; CK_BYTE_PTR pModulus, pExponent; CK_ATTRIBUTE template[] = { {CKA_MODULUS, NULL_PTR, 0}, {CKA_PUBLIC_EXPONENT, NULL_PTR, 0} }; CK_RV rv; . . . rv = C_GetAttributeValue(hSession, hObject, &template, 2); if (rv == CKR_OK) { pModulus = (CK_BYTE_PTR) malloc(template[0].ulValueLen); template[0].pValue = pModulus; /* template[0].ulValueLen was set by C_GetAttributeValue */ pExponent = (CK_BYTE_PTR) malloc(template[1].ulValueLen); template[1].pValue = pExponent; /* template[1].ulValueLen was set by C_GetAttributeValue */ rv = C_GetAttributeValue(hSession, hObject, &template, 2); if (rv == CKR_OK) { . . . } free(pModulus); free(pExponent); }
CK_RV C_SetAttributeValue( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount);
C_SetAttributeValue modifies the value of one or more attributes of an object.
| hSession | is the session's handle; |
| hObject | is the object's handle; |
| pTemplate | points to a template that specifies which attribute values are to be modified and their new values; |
| ulCount | is the number of attributes in the template. |
The template may specify new values for any attributes of the object that can be modified. If the template specifies a value of an attribute which is incompatible with other existing attributes of the object, the call fails with the return code CKR_TEMPLATE_INCONSISTENT.
Not all attributes can be modified; see Section 9.7 for more details.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hObject; CK_UTF8CHAR label[] = {"New label"}; CK_ATTRIBUTE template[] = { CKA_LABEL, label, sizeof(label)-1 }; CK_RV rv; . . . rv = C_SetAttributeValue(hSession, hObject, &template, 1); if (rv == CKR_OK) { . . . }
CK_RV C_FindObjectsInit( CK_SESSION_HANDLE hSession, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount);
C_FindObjectsInit initializes a search for token and session objects that match a template.
| hSession | is the session's handle; |
| pTemplate | points to a search template that specifies the attribute values to match; |
| ulCount | is the number of attributes in the search template. The matching criterion is an exact byte-for-byte match with all attributes in the template. To find all objects, set ulCount to 0. |
The object search operation will only find objects that the session can view. For example, an object search in an "R/W Public Session" will not find any private objects (even if one of the attributes in the search template specifies that the search is for private objects).
If a search operation is active, and objects are created or destroyed which fit the search template for the active search operation, then those objects may or may not be found by the search operation. Note that this means that, under these circumstances, the search operation may return invalid object handles.
Even though C_FindObjectsInit can return the values CKR_ATTRIBUTE_TYPE_INVALID and CKR_ATTRIBUTE_VALUE_INVALID, it is not required to. For example, if it is given a search template with nonexistent attributes in it, it can return CKR_ATTRIBUTE_TYPE_INVALID, or it can initialize a search operation which will match no objects and return CKR_OK.
CK_RV C_FindObjects( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE_PTR phObject, CK_ULONG ulMaxObjectCount, CK_ULONG_PTR pulObjectCount);
C_FindObjects continues a search for token and session objects that match a template, obtaining additional object handles.
| hSession | is the session's handle; |
| phObject | points to the location that receives the list (array) of additional object handles; |
| ulMaxObjectCount | is the maximum number of object handles to be returned; |
| pulObjectCount | points to the location that receives the actual number of object handles returned. |
The search must have been initialized with C_FindObjectsInit.
CK_RV C_FindObjectsFinal( CK_SESSION_HANDLE hSession);
C_FindObjectsFinal terminates a search for token and session objects.
| hSession | is the session's handle. |
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hObject; CK_ULONG ulObjectCount; CK_RV rv; . . . rv = C_FindObjectsInit(hSession, NULL_PTR, 0); assert(rv == CKR_OK); while (1) { rv = C_FindObjects(hSession, &hObject, 1, &ulObjectCount); if (rv != CKR_OK || ulObjectCount == 0) break; . . . } rv = C_FindObjectsFinal(hSession); assert(rv == CKR_OK);