gecko/security/nss/lib/ckfw/ck.api
2008-06-06 08:40:11 -04:00

576 lines
23 KiB
Plaintext

#
# ***** BEGIN LICENSE BLOCK *****
# Version: MPL 1.1/GPL 2.0/LGPL 2.1
#
# The contents of this file are subject to the Mozilla Public License Version
# 1.1 (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
# http://www.mozilla.org/MPL/
#
# Software distributed under the License is distributed on an "AS IS" basis,
# WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
# for the specific language governing rights and limitations under the
# License.
#
# The Original Code is the Netscape security libraries.
#
# The Initial Developer of the Original Code is
# Netscape Communications Corporation.
# Portions created by the Initial Developer are Copyright (C) 1994-2000
# the Initial Developer. All Rights Reserved.
#
# Contributor(s):
#
# Alternatively, the contents of this file may be used under the terms of
# either the GNU General Public License Version 2 or later (the "GPL"), or
# the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
# in which case the provisions of the GPL or the LGPL are applicable instead
# of those above. If you wish to allow use of your version of this file only
# under the terms of either the GPL or the LGPL, and not to allow others to
# use your version of this file under the terms of the MPL, indicate your
# decision by deleting the provisions above and replace them with the notice
# and other provisions required by the GPL or the LGPL. If you do not delete
# the provisions above, a recipient may use your version of this file under
# the terms of any one of the MPL, the GPL or the LGPL.
#
# ***** END LICENSE BLOCK *****
# This file is in part derived from a file "pkcs11f.h" made available
# by RSA Security at ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-11/pkcs11f.h
CVS_ID "@(#) $RCSfile: ck.api,v $ $Revision: 1.3 $ $Date: 2005/02/02 22:28:11 $"
# Fields
# FUNCTION introduces a Cryptoki function
# CK_type specifies and introduces an argument
#
# General-purpose
# C_Initialize initializes the Cryptoki library.
FUNCTION C_Initialize
CK_VOID_PTR pInitArgs # if this is not NULL_PTR, it gets
# cast to CK_C_INITIALIZE_ARGS_PTR
# and dereferenced
# C_Finalize indicates that an application is done with the
# Cryptoki library.
FUNCTION C_Finalize
CK_VOID_PTR pReserved # reserved. Should be NULL_PTR
# C_GetInfo returns general information about Cryptoki.
FUNCTION C_GetInfo
CK_INFO_PTR pInfo # location that receives information
# C_GetFunctionList returns the function list.
FUNCTION C_GetFunctionList
CK_FUNCTION_LIST_PTR_PTR ppFunctionList # receives pointer to function
# list
# Slot and token management
# C_GetSlotList obtains a list of slots in the system.
FUNCTION C_GetSlotList
CK_BBOOL tokenPresent # only slots with tokens?
CK_SLOT_ID_PTR pSlotList # receives array of slot IDs
CK_ULONG_PTR pulCount # receives number of slots
# C_GetSlotInfo obtains information about a particular slot in the
# system.
FUNCTION C_GetSlotInfo
CK_SLOT_ID slotID # the ID of the slot
CK_SLOT_INFO_PTR pInfo # receives the slot information
# C_GetTokenInfo obtains information about a particular token in the
# system.
FUNCTION C_GetTokenInfo
CK_SLOT_ID slotID # ID of the token's slot
CK_TOKEN_INFO_PTR pInfo # receives the token information
# C_GetMechanismList obtains a list of mechanism types supported by a
# token.
FUNCTION C_GetMechanismList
CK_SLOT_ID slotID # ID of token's slot
CK_MECHANISM_TYPE_PTR pMechanismList # gets mech. array
CK_ULONG_PTR pulCount # gets # of mechs.
# C_GetMechanismInfo obtains information about a particular mechanism
# possibly supported by a token.
FUNCTION C_GetMechanismInfo
CK_SLOT_ID slotID # ID of the token's slot
CK_MECHANISM_TYPE type # type of mechanism
CK_MECHANISM_INFO_PTR pInfo # receives mechanism info
# C_InitToken initializes a token.
FUNCTION C_InitToken
CK_SLOT_ID slotID # ID of the token's slot
CK_CHAR_PTR pPin # the SO's initial PIN
CK_ULONG ulPinLen # length in bytes of the PIN
CK_CHAR_PTR pLabel # 32-byte token label (blank padded)
# C_InitPIN initializes the normal user's PIN.
FUNCTION C_InitPIN
CK_SESSION_HANDLE hSession # the session's handle
CK_CHAR_PTR pPin # the normal user's PIN
CK_ULONG ulPinLen # length in bytes of the PIN
# C_SetPIN modifies the PIN of the user who is logged in.
FUNCTION C_SetPIN
CK_SESSION_HANDLE hSession # the session's handle
CK_CHAR_PTR pOldPin # the old PIN
CK_ULONG ulOldLen # length of the old PIN
CK_CHAR_PTR pNewPin # the new PIN
CK_ULONG ulNewLen # length of the new PIN
# Session management
# C_OpenSession opens a session between an application and a token.
FUNCTION C_OpenSession
CK_SLOT_ID slotID # the slot's ID
CK_FLAGS flags # from CK_SESSION_INFO
CK_VOID_PTR pApplication # passed to callback
CK_NOTIFY Notify # callback function
CK_SESSION_HANDLE_PTR phSession # gets session handle
# C_CloseSession closes a session between an application and a token.
FUNCTION C_CloseSession
CK_SESSION_HANDLE hSession # the session's handle
# C_CloseAllSessions closes all sessions with a token.
FUNCTION C_CloseAllSessions
CK_SLOT_ID slotID # the token's slot
# C_GetSessionInfo obtains information about the session.
FUNCTION C_GetSessionInfo
CK_SESSION_HANDLE hSession # the session's handle
CK_SESSION_INFO_PTR pInfo # receives session info
# C_GetOperationState obtains the state of the cryptographic
# operation in a session.
FUNCTION C_GetOperationState
CK_SESSION_HANDLE hSession # session's handle
CK_BYTE_PTR pOperationState # gets state
CK_ULONG_PTR pulOperationStateLen # gets state length
# C_SetOperationState restores the state of the cryptographic
# operation in a session.
FUNCTION C_SetOperationState
CK_SESSION_HANDLE hSession # session's handle
CK_BYTE_PTR pOperationState # holds state
CK_ULONG ulOperationStateLen # holds state length
CK_OBJECT_HANDLE hEncryptionKey # en/decryption key
CK_OBJECT_HANDLE hAuthenticationKey # sign/verify key
# C_Login logs a user into a token.
FUNCTION C_Login
CK_SESSION_HANDLE hSession # the session's handle
CK_USER_TYPE userType # the user type
CK_CHAR_PTR pPin # the user's PIN
CK_ULONG ulPinLen # the length of the PIN
# C_Logout logs a user out from a token.
FUNCTION C_Logout
CK_SESSION_HANDLE hSession # the session's handle
# Object management
# C_CreateObject creates a new object.
FUNCTION C_CreateObject
CK_SESSION_HANDLE hSession # the session's handle
CK_ATTRIBUTE_PTR pTemplate # the object's template
CK_ULONG ulCount # attributes in template
CK_OBJECT_HANDLE_PTR phObject # gets new object's handle.
# C_CopyObject copies an object, creating a new object for the copy.
FUNCTION C_CopyObject
CK_SESSION_HANDLE hSession # the session's handle
CK_OBJECT_HANDLE hObject # the object's handle
CK_ATTRIBUTE_PTR pTemplate # template for new object
CK_ULONG ulCount # attributes in template
CK_OBJECT_HANDLE_PTR phNewObject # receives handle of copy
# C_DestroyObject destroys an object.
FUNCTION C_DestroyObject
CK_SESSION_HANDLE hSession # the session's handle
CK_OBJECT_HANDLE hObject # the object's handle
# C_GetObjectSize gets the size of an object in bytes.
FUNCTION C_GetObjectSize
CK_SESSION_HANDLE hSession # the session's handle
CK_OBJECT_HANDLE hObject # the object's handle
CK_ULONG_PTR pulSize # receives size of object
# C_GetAttributeValue obtains the value of one or more object
# attributes.
FUNCTION C_GetAttributeValue
CK_SESSION_HANDLE hSession # the session's handle
CK_OBJECT_HANDLE hObject # the object's handle
CK_ATTRIBUTE_PTR pTemplate # specifies attrs; gets vals
CK_ULONG ulCount # attributes in template
# C_SetAttributeValue modifies the value of one or more object
# attributes
FUNCTION C_SetAttributeValue
CK_SESSION_HANDLE hSession # the session's handle
CK_OBJECT_HANDLE hObject # the object's handle
CK_ATTRIBUTE_PTR pTemplate # specifies attrs and values
CK_ULONG ulCount # attributes in template
# C_FindObjectsInit initializes a search for token and session
# objects that match a template.
FUNCTION C_FindObjectsInit
CK_SESSION_HANDLE hSession # the session's handle
CK_ATTRIBUTE_PTR pTemplate # attribute values to match
CK_ULONG ulCount # attrs in search template
# C_FindObjects continues a search for token and session objects that
# match a template, obtaining additional object handles.
FUNCTION C_FindObjects
CK_SESSION_HANDLE hSession # session's handle
CK_OBJECT_HANDLE_PTR phObject # gets obj. handles
CK_ULONG ulMaxObjectCount # max handles to get
CK_ULONG_PTR pulObjectCount # actual # returned
# C_FindObjectsFinal finishes a search for token and session objects.
FUNCTION C_FindObjectsFinal
CK_SESSION_HANDLE hSession # the session's handle
# Encryption and decryption
# C_EncryptInit initializes an encryption operation.
FUNCTION C_EncryptInit
CK_SESSION_HANDLE hSession # the session's handle
CK_MECHANISM_PTR pMechanism # the encryption mechanism
CK_OBJECT_HANDLE hKey # handle of encryption key
# C_Encrypt encrypts single-part data.
FUNCTION C_Encrypt
CK_SESSION_HANDLE hSession # session's handle
CK_BYTE_PTR pData # the plaintext data
CK_ULONG ulDataLen # bytes of plaintext
CK_BYTE_PTR pEncryptedData # gets ciphertext
CK_ULONG_PTR pulEncryptedDataLen # gets c-text size
# C_EncryptUpdate continues a multiple-part encryption operation.
FUNCTION C_EncryptUpdate
CK_SESSION_HANDLE hSession # session's handle
CK_BYTE_PTR pPart # the plaintext data
CK_ULONG ulPartLen # plaintext data len
CK_BYTE_PTR pEncryptedPart # gets ciphertext
CK_ULONG_PTR pulEncryptedPartLen # gets c-text size
# C_EncryptFinal finishes a multiple-part encryption operation.
FUNCTION C_EncryptFinal
CK_SESSION_HANDLE hSession # session handle
CK_BYTE_PTR pLastEncryptedPart # last c-text
CK_ULONG_PTR pulLastEncryptedPartLen # gets last size
# C_DecryptInit initializes a decryption operation.
FUNCTION C_DecryptInit
CK_SESSION_HANDLE hSession # the session's handle
CK_MECHANISM_PTR pMechanism # the decryption mechanism
CK_OBJECT_HANDLE hKey # handle of decryption key
# C_Decrypt decrypts encrypted data in a single part.
FUNCTION C_Decrypt
CK_SESSION_HANDLE hSession # session's handle
CK_BYTE_PTR pEncryptedData # ciphertext
CK_ULONG ulEncryptedDataLen # ciphertext length
CK_BYTE_PTR pData # gets plaintext
CK_ULONG_PTR pulDataLen # gets p-text size
# C_DecryptUpdate continues a multiple-part decryption operation.
FUNCTION C_DecryptUpdate
CK_SESSION_HANDLE hSession # session's handle
CK_BYTE_PTR pEncryptedPart # encrypted data
CK_ULONG ulEncryptedPartLen # input length
CK_BYTE_PTR pPart # gets plaintext
CK_ULONG_PTR pulPartLen # p-text size
# C_DecryptFinal finishes a multiple-part decryption operation.
FUNCTION C_DecryptFinal
CK_SESSION_HANDLE hSession # the session's handle
CK_BYTE_PTR pLastPart # gets plaintext
CK_ULONG_PTR pulLastPartLen # p-text size
# Message digesting
# C_DigestInit initializes a message-digesting operation.
FUNCTION C_DigestInit
CK_SESSION_HANDLE hSession # the session's handle
CK_MECHANISM_PTR pMechanism # the digesting mechanism
# C_Digest digests data in a single part.
FUNCTION C_Digest
CK_SESSION_HANDLE hSession # the session's handle
CK_BYTE_PTR pData # data to be digested
CK_ULONG ulDataLen # bytes of data to digest
CK_BYTE_PTR pDigest # gets the message digest
CK_ULONG_PTR pulDigestLen # gets digest length
# C_DigestUpdate continues a multiple-part message-digesting operation.
FUNCTION C_DigestUpdate
CK_SESSION_HANDLE hSession # the session's handle
CK_BYTE_PTR pPart # data to be digested
CK_ULONG ulPartLen # bytes of data to be digested
# C_DigestKey continues a multi-part message-digesting operation, by
# digesting the value of a secret key as part of the data already
# digested.
FUNCTION C_DigestKey
CK_SESSION_HANDLE hSession # the session's handle
CK_OBJECT_HANDLE hKey # secret key to digest
# C_DigestFinal finishes a multiple-part message-digesting operation.
FUNCTION C_DigestFinal
CK_SESSION_HANDLE hSession # the session's handle
CK_BYTE_PTR pDigest # gets the message digest
CK_ULONG_PTR pulDigestLen # gets byte count of digest
# Signing and MACing
# C_SignInit initializes a signature (private key encryption)
# operation, where the signature is (will be) an appendix to the
# data, and plaintext cannot be recovered from the signature.
FUNCTION C_SignInit
CK_SESSION_HANDLE hSession # the session's handle
CK_MECHANISM_PTR pMechanism # the signature mechanism
CK_OBJECT_HANDLE hKey # handle of signature key
# C_Sign signs (encrypts with private key) data in a single part,
# where the signature is (will be) an appendix to the data, and
# plaintext cannot be recovered from the signature.
FUNCTION C_Sign
CK_SESSION_HANDLE hSession # the session's handle
CK_BYTE_PTR pData # the data to sign
CK_ULONG ulDataLen # count of bytes to sign
CK_BYTE_PTR pSignature # gets the signature
CK_ULONG_PTR pulSignatureLen # gets signature length
# C_SignUpdate continues a multiple-part signature operation, where
# the signature is (will be) an appendix to the data, and plaintext
# cannot be recovered from the signature.
FUNCTION C_SignUpdate
CK_SESSION_HANDLE hSession # the session's handle
CK_BYTE_PTR pPart # the data to sign
CK_ULONG ulPartLen # count of bytes to sign
# C_SignFinal finishes a multiple-part signature operation, returning
# the signature.
FUNCTION C_SignFinal
CK_SESSION_HANDLE hSession # the session's handle
CK_BYTE_PTR pSignature # gets the signature
CK_ULONG_PTR pulSignatureLen # gets signature length
# C_SignRecoverInit initializes a signature operation, where the data
# can be recovered from the signature.
FUNCTION C_SignRecoverInit
CK_SESSION_HANDLE hSession # the session's handle
CK_MECHANISM_PTR pMechanism # the signature mechanism
CK_OBJECT_HANDLE hKey # handle of the signature key
# C_SignRecover signs data in a single operation, where the data can
# be recovered from the signature.
FUNCTION C_SignRecover
CK_SESSION_HANDLE hSession # the session's handle
CK_BYTE_PTR pData # the data to sign
CK_ULONG ulDataLen # count of bytes to sign
CK_BYTE_PTR pSignature # gets the signature
CK_ULONG_PTR pulSignatureLen # gets signature length
# Verifying signatures and MACs
# C_VerifyInit initializes a verification operation, where the
# signature is an appendix to the data, and plaintext cannot cannot
# be recovered from the signature (e.g. DSA).
FUNCTION C_VerifyInit
CK_SESSION_HANDLE hSession # the session's handle
CK_MECHANISM_PTR pMechanism # the verification mechanism
CK_OBJECT_HANDLE hKey # verification key
# C_Verify verifies a signature in a single-part operation, where the
# signature is an appendix to the data, and plaintext cannot be
# recovered from the signature.
FUNCTION C_Verify
CK_SESSION_HANDLE hSession # the session's handle
CK_BYTE_PTR pData # signed data
CK_ULONG ulDataLen # length of signed data
CK_BYTE_PTR pSignature # signature
CK_ULONG ulSignatureLen # signature length
# C_VerifyUpdate continues a multiple-part verification operation,
# where the signature is an appendix to the data, and plaintext cannot be
# recovered from the signature.
FUNCTION C_VerifyUpdate
CK_SESSION_HANDLE hSession # the session's handle
CK_BYTE_PTR pPart # signed data
CK_ULONG ulPartLen # length of signed data
# C_VerifyFinal finishes a multiple-part verification operation,
# checking the signature.
FUNCTION C_VerifyFinal
CK_SESSION_HANDLE hSession # the session's handle
CK_BYTE_PTR pSignature # signature to verify
CK_ULONG ulSignatureLen # signature length
# C_VerifyRecoverInit initializes a signature verification operation,
# where the data is recovered from the signature.
FUNCTION C_VerifyRecoverInit
CK_SESSION_HANDLE hSession # the session's handle
CK_MECHANISM_PTR pMechanism # the verification mechanism
CK_OBJECT_HANDLE hKey # verification key
# C_VerifyRecover verifies a signature in a single-part operation,
# where the data is recovered from the signature.
FUNCTION C_VerifyRecover
CK_SESSION_HANDLE hSession # the session's handle
CK_BYTE_PTR pSignature # signature to verify
CK_ULONG ulSignatureLen # signature length
CK_BYTE_PTR pData # gets signed data
CK_ULONG_PTR pulDataLen # gets signed data len
# Dual-function cryptographic operations
# C_DigestEncryptUpdate continues a multiple-part digesting and
# encryption operation.
FUNCTION C_DigestEncryptUpdate
CK_SESSION_HANDLE hSession # session's handle
CK_BYTE_PTR pPart # the plaintext data
CK_ULONG ulPartLen # plaintext length
CK_BYTE_PTR pEncryptedPart # gets ciphertext
CK_ULONG_PTR pulEncryptedPartLen # gets c-text length
# C_DecryptDigestUpdate continues a multiple-part decryption and
# digesting operation.
FUNCTION C_DecryptDigestUpdate
CK_SESSION_HANDLE hSession # session's handle
CK_BYTE_PTR pEncryptedPart # ciphertext
CK_ULONG ulEncryptedPartLen # ciphertext length
CK_BYTE_PTR pPart # gets plaintext
CK_ULONG_PTR pulPartLen # gets plaintext len
# C_SignEncryptUpdate continues a multiple-part signing and
# encryption operation.
FUNCTION C_SignEncryptUpdate
CK_SESSION_HANDLE hSession # session's handle
CK_BYTE_PTR pPart # the plaintext data
CK_ULONG ulPartLen # plaintext length
CK_BYTE_PTR pEncryptedPart # gets ciphertext
CK_ULONG_PTR pulEncryptedPartLen # gets c-text length
# C_DecryptVerifyUpdate continues a multiple-part decryption and
# verify operation.
FUNCTION C_DecryptVerifyUpdate
CK_SESSION_HANDLE hSession # session's handle
CK_BYTE_PTR pEncryptedPart # ciphertext
CK_ULONG ulEncryptedPartLen # ciphertext length
CK_BYTE_PTR pPart # gets plaintext
CK_ULONG_PTR pulPartLen # gets p-text length
# Key management
# C_GenerateKey generates a secret key, creating a new key object.
FUNCTION C_GenerateKey
CK_SESSION_HANDLE hSession # the session's handle
CK_MECHANISM_PTR pMechanism # key generation mech.
CK_ATTRIBUTE_PTR pTemplate # template for new key
CK_ULONG ulCount # # of attrs in template
CK_OBJECT_HANDLE_PTR phKey # gets handle of new key
# C_GenerateKeyPair generates a public-key/private-key pair, creating
# new key objects.
FUNCTION C_GenerateKeyPair
CK_SESSION_HANDLE hSession # session handle
CK_MECHANISM_PTR pMechanism # key-gen mech.
CK_ATTRIBUTE_PTR pPublicKeyTemplate # template for pub. key
CK_ULONG ulPublicKeyAttributeCount # # pub. attrs.
CK_ATTRIBUTE_PTR pPrivateKeyTemplate # template for priv. key
CK_ULONG ulPrivateKeyAttributeCount # # priv. attrs.
CK_OBJECT_HANDLE_PTR phPublicKey # gets pub. key handle
CK_OBJECT_HANDLE_PTR phPrivateKey # gets priv. key handle
# C_WrapKey wraps (i.e., encrypts) a key.
FUNCTION C_WrapKey
CK_SESSION_HANDLE hSession # the session's handle
CK_MECHANISM_PTR pMechanism # the wrapping mechanism
CK_OBJECT_HANDLE hWrappingKey # wrapping key
CK_OBJECT_HANDLE hKey # key to be wrapped
CK_BYTE_PTR pWrappedKey # gets wrapped key
CK_ULONG_PTR pulWrappedKeyLen # gets wrapped key size
# C_UnwrapKey unwraps (decrypts) a wrapped key, creating a new key
# object.
FUNCTION C_UnwrapKey
CK_SESSION_HANDLE hSession # session's handle
CK_MECHANISM_PTR pMechanism # unwrapping mech.
CK_OBJECT_HANDLE hUnwrappingKey # unwrapping key
CK_BYTE_PTR pWrappedKey # the wrapped key
CK_ULONG ulWrappedKeyLen # wrapped key len
CK_ATTRIBUTE_PTR pTemplate # new key template
CK_ULONG ulAttributeCount # template length
CK_OBJECT_HANDLE_PTR phKey # gets new handle
# C_DeriveKey derives a key from a base key, creating a new key object.
FUNCTION C_DeriveKey
CK_SESSION_HANDLE hSession # session's handle
CK_MECHANISM_PTR pMechanism # key deriv. mech.
CK_OBJECT_HANDLE hBaseKey # base key
CK_ATTRIBUTE_PTR pTemplate # new key template
CK_ULONG ulAttributeCount # template length
CK_OBJECT_HANDLE_PTR phKey # gets new handle
# Random number generation
# C_SeedRandom mixes additional seed material into the token's random
# number generator.
FUNCTION C_SeedRandom
CK_SESSION_HANDLE hSession # the session's handle
CK_BYTE_PTR pSeed # the seed material
CK_ULONG ulSeedLen # length of seed material
# C_GenerateRandom generates random data.
FUNCTION C_GenerateRandom
CK_SESSION_HANDLE hSession # the session's handle
CK_BYTE_PTR RandomData # receives the random data
CK_ULONG ulRandomLen # # of bytes to generate
# Parallel function management
# C_GetFunctionStatus is a legacy function; it obtains an updated
# status of a function running in parallel with an application.
FUNCTION C_GetFunctionStatus
CK_SESSION_HANDLE hSession # the session's handle
# C_CancelFunction is a legacy function; it cancels a function running
# in parallel.
FUNCTION C_CancelFunction
CK_SESSION_HANDLE hSession # the session's handle
# Functions added in for Cryptoki Version 2.01 or later
# C_WaitForSlotEvent waits for a slot event (token insertion, removal,
# etc.) to occur.
FUNCTION C_WaitForSlotEvent
CK_FLAGS flags # blocking/nonblocking flag
CK_SLOT_ID_PTR pSlot # location that receives the slot ID
CK_VOID_PTR pRserved # reserved. Should be NULL_PTR
## C_ConfigureSlot passes an installation-specified bytestring to a
## slot.
#FUNCTION C_ConfigureSlot
#CK_SLOT_ID slotID # the slot to configure
#CK_BYTE_PTR pConfig # the configuration string
#CK_ULONG ulConfigLen # length of the config string