Skip to content

Correct doc comments that describe the wrong behavior #294

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
LinuxJedi merged 1 commit into from
Nov 10, 2026
Merged

Correct doc comments that describe the wrong behavior #294

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 20 additions & 12 deletions src/crypto.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5476,7 +5476,6 @@ CK_RV C_DecryptFinal(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pLastPart,

/**
* Initialize digest operation.
* No digest mechanisms are supported.
*
* @param hSession [in] Handle of session.
* @param pMechanism [in] Type of operation to perform with parameters.
Expand All @@ -5486,6 +5485,7 @@ CK_RV C_DecryptFinal(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pLastPart,
* instead cancel the active operation and return CKR_OK.
* CKR_MECHANISM_INVALID when the mechanism is not supported with this
* type of operation.
* CKR_OK on success.
*/
CK_RV C_DigestInit(CK_SESSION_HANDLE hSession,
CK_MECHANISM_PTR pMechanism)
Expand Down Expand Up @@ -5551,12 +5551,11 @@ CK_RV C_DigestInit(CK_SESSION_HANDLE hSession,

/**
* Digest single-part data.
* No digest mechanisms are supported.
*
* @param hSession [in] Handle of session.
* @param pData [in] Data to be digested.
* @param ulDataLen [in] Length of data in bytes.
* @param pDigest [in] Buffer to hold digest output.
* @param pDigest [out] Buffer to hold digest output.
* NULL indicates length required.
* @param pulDigestLen [in,out] On in, length of the buffer.
* On out, length of the digest data in bytes.
Expand All @@ -5565,6 +5564,7 @@ CK_RV C_DigestInit(CK_SESSION_HANDLE hSession,
* CKR_ARGUMENTS_BAD when pData or pulDigestLen is NULL.
* CKR_OPERATION_NOT_INITIALIZED when C_DigestInit has not been
* successfully called.
* CKR_OK on success.
*/
CK_RV C_Digest(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData,
CK_ULONG ulDataLen, CK_BYTE_PTR pDigest,
Expand Down Expand Up @@ -5618,7 +5618,6 @@ CK_RV C_Digest(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData,

/**
* Continue digesting multi-part data.
* No digest mechanisms are supported.
*
* @param hSession [in] Handle of session.
* @param pPart [in] Data to be digested.
Expand All @@ -5628,6 +5627,7 @@ CK_RV C_Digest(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData,
* CKR_ARGUMENTS_BAD when pPart is NULL.
* CKR_OPERATION_NOT_INITIALIZED when C_DigestInit has not been
* successfully called.
* CKR_OK on success.
*/
CK_RV C_DigestUpdate(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pPart,
CK_ULONG ulPartLen)
Expand Down Expand Up @@ -5671,7 +5671,6 @@ CK_RV C_DigestUpdate(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pPart,

/**
* Continues digesting multi-part data by digesting the value in the key.
* No digest mechanisms are supported.
*
* @param hSession [in] Handle of session.
* @param hKey [in] Handle of a key object.
Expand All @@ -5680,6 +5679,7 @@ CK_RV C_DigestUpdate(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pPart,
* CKR_KEY_HANDLE_INVALID when key object handle is not valid.
* CKR_OPERATION_NOT_INITIALIZED when C_DigestInit has not been
* successfully called.
* CKR_OK on success.
*/
static CK_RV wp11_C_DigestKey(CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hKey)
{
Expand Down Expand Up @@ -5745,10 +5745,9 @@ CK_RV C_DigestKey(CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hKey)

/**
* Finished digesting multi-part data.
* No digest mechanisms are supported.
*
* @param hSession [in] Handle of session.
* @param pDigest [in] Buffer to hold digest output.
* @param pDigest [out] Buffer to hold digest output.
* NULL indicates length required.
* @param pulDigestLen [in,out] On in, length of the buffer.
* On out, length of the digest data in bytes.
Expand All @@ -5757,6 +5756,7 @@ CK_RV C_DigestKey(CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hKey)
* CKR_ARGUMENTS_BAD when pulDigestLen is NULL.
* CKR_OPERATION_NOT_INITIALIZED when C_DigestInit has not been
* successfully called.
* CKR_OK on success.
*/
CK_RV C_DigestFinal(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pDigest,
CK_ULONG_PTR pulDigestLen)
Expand Down Expand Up @@ -10304,24 +10304,32 @@ CK_RV C_WrapKey(CK_SESSION_HANDLE hSession,
}

/**
* Unwrap a key using a wrap key.
* Support only RSA private key wrapped by AESCBCPAD mechanism
* Unwrap an RSA private key or an AES, HKDF or generic secret key with AES key
* wrap (padded or not), AES-CBC-PAD, AES-ECB or RSA PKCS#1 v1.5, as built.
*
* @param hSession [in] Handle of session.
* @param pMechanism [in] Type of operation to perform with
* parameters.
* @param hUnwrappingKey [in] Handle of key to unwrap with.
* @param pWrappedKey [in] Buffer to hold wrapped key.
* @param pulWrappedKeyLen [in] Length of wrapped key in bytes.
* @param pWrappedKey [in] Wrapped key data.
* @param ulWrappedKeyLen [in] Length of wrapped key in bytes.
* @param pTemplate [in] Array of attributes to create key object
* with.
* @param ulAttributeCount [in] Count of array elements.
* @param phKey [out] Handle of unwrapped key.
* @return CKR_CRYPTOKI_NOT_INITIALIZED when library not initialized.
* CKR_SESSION_HANDLE_INVALID when session handle is not valid.
* CKR_ARGUMENTS_BAD when pMechanism or pulWrappedKeyLen is NULL.
* CKR_ARGUMENTS_BAD when pMechanism, pWrappedKey, pTemplate or phKey
* is NULL, or ulWrappedKeyLen is 0.
* CKR_UNWRAPPING_KEY_HANDLE_INVALID when the unwrapping key handle is
* not valid.
* CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT when the unwrapping key type
* does not match the mechanism.
* CKR_WRAPPED_KEY_LEN_RANGE when the wrapped or unwrapped key length
* is not valid.
* CKR_WRAPPED_KEY_INVALID when the wrapped key does not unwrap to a
* valid key.
* CKR_OK on success.
* CKR_TEMPLATE_INCONSISTENT when the template's key type cannot be
* unwrapped.
* CKR_MECHANISM_INVALID when the mechanism is not supported with this
Expand Down
19 changes: 10 additions & 9 deletions src/internal.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12111,7 +12111,7 @@ int WP11_Slot_TokenFailedLogin(WP11_Slot* slot, int login)
*
* @param slot [in] Slot object.
* @param login [in] Security officer or user.
* @return Count of consecutive failed logins.
* @return Time of the last failed login plus the lockout timeout.
*/
time_t WP11_Slot_TokenFailedExpire(WP11_Slot* slot, int login)
{
Expand Down Expand Up @@ -12209,11 +12209,12 @@ int WP11_Session_GetState(WP11_Session* session)
}

/**
* Return whether this session is in use.
* Return whether this session is read/write. NSS builds treat every session
* as read/write.
*
* @param session [in] Session object.
* @return 1 when session is in used.
* 0 when session is not in used.
* @return 1 when session is read/write.
* 0 otherwise.
*/
int WP11_Session_IsRW(WP11_Session* session)
{
Expand All @@ -12230,8 +12231,8 @@ int WP11_Session_IsRW(WP11_Session* session)
*
* @param session [in] Session object.
* @param init [in] Operation to check.
* @return 1 when session is in used.
* 0 when session is not in used.
* @return 1 when the session's operation is init.
* 0 otherwise.
*/
int WP11_Session_IsOpInitialized(WP11_Session* session, int init)
{
Expand Down Expand Up @@ -12559,8 +12560,8 @@ static int MechanismToHash(int mechanism)
*
* @param session [in] Session object.
* @param mechanism [in] Mechanism to check against.
* @return 1 when session is in used.
* 0 when session is not in used.
* @return 1 when the session's hash operation uses the mechanism's hash.
* 0 otherwise.
*/
int WP11_Session_IsHashOpInitialized(WP11_Session* session, int mechanism)
{
Expand Down Expand Up @@ -15286,7 +15287,7 @@ int WP11_Object_SetMlKemKey(WP11_Object* object, unsigned char** data,
#endif /* WOLFPKCS11_MLKEM */

/**
* Set the DH key data into the object.
* Set the secret key data into the object.
*
* @param object [in] Object object.
* @param data [in] Array of byte arrays.
Expand Down
10 changes: 6 additions & 4 deletions src/slot.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1868,18 +1868,20 @@ CK_RV C_GetOperationState(CK_SESSION_HANDLE hSession,
}

/**
* Get the state of the current operation.
* Only intended for Digest state.
* Replace the session's operation with the digest operation held in
* serialized state.
*
* @param hSession [in] Session handle.
* @param pOperationState [in] Serialized state.
* @param ulOperationStateLen [in] Length of serialized state in bytes.
* @param hEncryptionKey [in] Object handle for encryption key.
* @param hAuthenticationKey [in] Object handle for authentication key.
* @param hEncryptionKey [in] Must be CK_INVALID_HANDLE.
* @param hAuthenticationKey [in] Must be CK_INVALID_HANDLE.
* @return CKR_CRYPTOKI_NOT_INITIALIZED when library not initialized.
* CKR_SESSION_HANDLE_INVALID when session handle is not valid.
* CKR_ARGUMENTS_BAD when pOperationState is NULL.
* CKR_KEY_NOT_NEEDED when a key handle is given.
* CKR_SAVED_STATE_INVALID indicating the state is not valid.
* CKR_OK on success.
*/
CK_RV C_SetOperationState(CK_SESSION_HANDLE hSession,
CK_BYTE_PTR pOperationState,
Expand Down
6 changes: 4 additions & 2 deletions src/wolfpkcs11.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -589,8 +589,10 @@ CK_RV C_Initialize(CK_VOID_PTR pInitArgs)
/**
* Finalize the Crypto-Ki library.
*
* @param pReserved [out] Ignored.
* @return CKR_FUNCTION_FAILED when token state could not be stored, in which
* @param pReserved [in] Reserved; must be NULL.
* @return CKR_CRYPTOKI_NOT_INITIALIZED when library not initialized.
* CKR_ARGUMENTS_BAD when pReserved is not NULL.
* CKR_FUNCTION_FAILED when token state could not be stored, in which
* case the library is finalized all the same, or when the
* initialization lock could not be taken, in which case it stays
* initialized and the call can be retried.
Expand Down
2 changes: 1 addition & 1 deletion wolfpkcs11/internal.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,7 @@ C_EXTRA_FLAGS="-DWOLFSSL_PUBLIC_MP -DWC_RSA_DIRECT"
#endif
#endif

/* Session was opened read-only or read/write. */
/* Token initialization state. */
#define WP11_TOKEN_STATE_UNKNOWN 0
#define WP11_TOKEN_STATE_INITIALIZED 1

Expand Down
Loading