idnits 2.17.1 draft-smyslov-crypto-api-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == There is 1 instance of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 7) being 59 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 25 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([IPsec], [TLS], [ISAKMP], [IKE]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 1200 has weird spacing: '... struct tag_C...' == Line 1201 has weird spacing: '... long sta...' == Line 1202 has weird spacing: '... long typ...' == Line 1204 has weird spacing: '... long id;...' == Line 1205 has weird spacing: '... long gro...' == (16 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (April 1999) is 9142 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 1233 -- Possible downref: Non-RFC (?) normative reference: ref. 'Schneier' ** Obsolete normative reference: RFC 2401 (ref. 'IPsec') (Obsoleted by RFC 4301) ** Obsolete normative reference: RFC 2408 (ref. 'ISAKMP') (Obsoleted by RFC 4306) ** Obsolete normative reference: RFC 2409 (ref. 'IKE') (Obsoleted by RFC 4306) ** Obsolete normative reference: RFC 2246 (ref. 'TLS') (Obsoleted by RFC 4346) Summary: 10 errors (**), 0 flaws (~~), 10 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT V. Smyslov 2 draft-smyslov-crypto-api-00.txt TWS 3 Expires: October 1999 April 1999 5 SIMPLE CRYPTOGRAPHIC PROGRAM INTERFACE (Crypto API) 7 Status of this Memo 9 This document is an Internet-Draft and is in full conformance with all 10 provisions of Section 10 of RFC2026 except that the right to produce 11 derivative works is not granted. 13 Internet-Drafts are working documents of the Internet Engineering Task 14 Force (IETF), its areas, and its working groups. Note that other 15 groups may also distribute working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet- Drafts as reference 20 material or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt 25 The list of Internet-Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html. 28 Abstract 30 This document describes simple Application Program Interface to 31 cryptographic functions. The main purpose of such an interface is to 32 separate cryptographic libraries from internet applications, thus 33 allowing an independent development of both. It can be used in various 34 internet application, such as [IPsec], [ISAKMP], [IKE], [TLS]. 36 Table of Contents 38 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . 2 39 1.1. Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 40 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 41 1.3. Objectives of Development . . . . . . . . . . . . . . . . . . 3 42 2. Cryptoplugin Structure. . . . . . . . . . . . . . . . . . . . . 3 43 3. Program Interface . . . . . . . . . . . . . . . . . . . . . . . 4 44 3.1. Cryptoplugin Initialization Function. . . . . . . . . . . . . 4 45 3.1.1. Description of CryptoPluginInfo structure . . . . . . . . . 5 46 3.1.2. Description of CryptoAlgInfo structure. . . . . . . . . . . 6 47 3.2. Cryptoplugin Deinitialization Function. . . . . . . . . . . . 9 48 3.3. Cryptographic Context Opening Function. . . . . . . . . . . . 9 49 3.4. Cryptographic Context Reopening Function. . . . . . . . . . . 10 50 3.5. Cryptographic Context Closing Function. . . . . . . . . . . . 11 51 3.6. Key Verification Function . . . . . . . . . . . . . . . . . . 11 52 3.7. Data Transformation Function. . . . . . . . . . . . . . . . . 12 53 3.7.1. For CRYPTO_TYPE_ENCRYPT Algorithm Type. . . . . . . . . . . 12 54 3.7.2. For CRYPTO_TYPE_DECRYPT Algorithm Type. . . . . . . . . . . 13 55 3.7.3. For CRYPTO_TYPE_SIGN Algorithm Type . . . . . . . . . . . . 14 56 3.7.4. For CRYPTO_TYPE_VERIFY Algorithm Type . . . . . . . . . . . 15 57 3.7.5. For CRYPTO_TYPE_COMPRESS Algorithm Type . . . . . . . . . . 16 58 3.7.6. For CRYPTO_TYPE_UNCOMPRESS Algorithm Type . . . . . . . . . 17 59 3.7.7. For CRYPTO_TYPE_HASH Algorithm Type . . . . . . . . . . . . 18 60 3.7.8. For CRYPTO_TYPE_RANDOM Algorithm Type. . . . . . . . . . . 19 61 3.8. Cryptographic Context Control Function. . . . . . . . . . . . 20 62 4. Cryptoplugin Registration Procedure . . . . . . . . . . . . . . 21 63 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 21 64 6. References. . . . . . . . . . . . . . . . . . . . . . . . . . . 21 65 7. Author's Address . . . . . . . . . . . . . . . . . . . . . . . 21 66 Appendix A. The interface specification as a C header file . . . . 22 68 1. Introduction 70 1.1. Summary 72 Nowadays internet applications, that require cryptographic functions at 73 the level of operating system kernel, use the method that assumes the 74 libraries must be compiled/linked together with the module (driver) 75 which provides product functionality. For the sake of possibility of 76 independent development of the cryptographic modules and in order to 77 provide a simple, effective and universal (suitable for application and 78 as well kernel level of operating system) solution this specification 79 offers the method to extract encrypting algorithms to the separate 80 cryptographic modules. 82 This document describes simple open interface (Crypto API) to external 83 cryptographic libraries optimized both for the application and kernel 84 level of the operating system. 86 1.2. Terminology 88 Cryptoplugin 90 Operation system unit (driver, shared library, module) that provides 91 cryptographic functions via well-defined (but OS-specific) interface. 93 Cryptolibrary 95 Part of cryptoplugin that provides its cryptographic functionality via 96 Crypto API. 98 Wrapper 100 Part of cryptoplugin that provides interfaces translation between 101 Crypto API and OS-specific interface. 103 Definition of all cryptography related terms can be found in 104 [Schneier]. 106 1.3. Objectives of Development 108 The objectives of Simple CryptoAPI development are as follows: 110 1) To extract program implementations of encryption, one-way hash 111 function, digital signature and random numbers generation algorithms 112 to separate, independently developed modules. 114 2) To provide version independence between using encryption modules and 115 external cryptoplugin. 117 3) To ensure platform independent developments of encrypting algorithm 118 modules with portable source code. 120 4) To enable independent development of modules and compatibility of 121 modules developed independently. 123 2. Cryptoplugin Structure 125 In order to provide fast exchange between the cryptoplugin and its 126 client the cryptoplugin is implemented as a separate driver (or module) 127 of the particular operating system (Fig.1). Cryptoplugin consists of 128 two parts (Fig.2): 130 1) cryptolibrary itself (1) 132 2) system-dependent module (wrapper) for interaction between 133 cryptolibrary and its client (2) 135 Cryptoplugin initialization 136 / by the operating system 137 | 138 | 139 +------------------+ +-|-+-------------+ 140 | | | | | 141 | Cryptoplugin's | -------> | | 142 | | | Cryptoplugin | 143 | client | <------- | | 144 | | | | | 145 +------------------+ | +---+-------------+ 146 | 147 \ 148 \ System-dependent CPI 150 Fig. 1 Interaction between cryptoplugin and its client 151 +---------------+-------------------------------+ 152 | | | 153 | --> Submodule of | 154 | Submodule - | | 155 | | encrypting algorithms (1) | 156 | wrapper (2) | | 157 | <-- (cryptolibrary) | 158 | | | 159 +---------------+-------------------------------+ 160 | 161 \ 162 \ Cryptographic Program Interface 164 Fig. 2 Cryptoplugin structure 166 The system-dependent module (wrapper) is delivered by the driver-client 167 developer in the form of source code or in the form of libraries (for 168 example, in the form of object files) for particular operating system. 169 The wrapper is intended for translation of system-independent 170 application interface to the particular system-dependent interface with 171 the cryptoplugin's client. The wrapper context does not include 172 components specific to cryptoplugin's client functionality or to some 173 cryptographic algorithm. The interface described in section 3 is the 174 standard for interaction between the submodules (1) and (2). 176 A cryptoplugin can contain a number of different algorithms. Moreover, 177 it can contain some different implementations of one particular 178 algorithm. 180 3. Program Interface 182 The CPI (Cryptographic Program Interface) consists of a set of 183 functions exported by encrypting algorithm submodule (cryptolibrary). 184 The interface functions are described below (see also Appendix A). 186 3.1. Cryptoplugin Initialization Function 188 The function is intended for cryptoplugin initialization and obtaining 189 information about algorithms contained in cryptoplugin. The function is 190 called once before the beginning of cryptoplugin operation. 192 /* CryptoPlugin initialization. Returns pointer to CryptoPluginInfo 193 structure on success or NULL on fatal error. */ 194 CryptoPluginInfo *CryptoPluginInit( 195 void *param);/* Ptr to OS parameters 196 (platform-specific) */ 198 Description of parameters: 200 param - pointer to system-dependent parameters transmitted to 201 cryptoplugin by the operating system. Intention and 202 format of parameters are specific to each operating 203 system and should be described in documentation on the 204 cryptoplugin wrapper. 206 The function is called at the moment of cryptoplugin initialization. If 207 succeeded it returns the pointer to CryptoPluginInfo structure that 208 describes the module and algorithms implemented in the cryptolibrary. 209 If function call did not succeed, function will return NULL or 210 appropriate error code in CryptoPluginInfo structure status field. If 211 the initialization is partially succeeded then the cryptoplugin either 212 returns CryptoPluginInfo structure transformed so that it contains only 213 successfully initialized algorithms or returns appropriate error code 214 in status field of CryptoAlgInfo structures that describes the reason 215 for the failure. 217 Error codes for the function: 219 NULL - fatal unsuccessful cryptoplugin initialization. The 220 module is unable even to indicate the reason of failure. 222 The pointer to cryptoplugin description structure in the case of full 223 or partial success. The status fields in CryptoPluginInfo structure and 224 in comprised CryptoAlgInfo structures can be set to the following 225 values: 227 CRYPTO_OK - cryptoplugin (algorithm) is initialized successfully. 229 CRYPTO_ERR_GENERAL - internal error. 231 CRYPTO_ERR_NOT_SUPPORTED - (only for algorithm) - the algorithm 232 is not supported by the module at the moment. 234 CRYPTO_ERR_HARDWARE - error of hardware initialization. 236 CRYPTO_ERR_NO_RESOURCES - insufficient internal resources. 238 CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general 239 CRYPTO_ERR_NO_RESOURCES error this code assumes that the calling module 240 can release system memory (if it is in position to) and try to call the 241 function once again. 243 3.1.1. Description of CryptoPluginInfo structure 245 The CryptoPluginInfo structure consists of header of fixed size that 246 generally describes cryptoplugin and array of CryptoAlgInfo structures 247 following the header. Each structure describes particular algorithm 248 implemented in the cryptolibrary (see Appendix A) 250 Structure fields description: 252 cpi_version - CPI version (should be CRYPTO_VER (1,0)). CPI version 253 determines both functions set and fields layout in 254 CryptoPluginInfo/CryptoAlgInfo structures. 256 status - returns the error code if cryptoplugin initialization 257 failed (otherwise should be CRYPTO_OK). 259 name - text cryptoplugin description (ASCII-7 characters only; 260 all unused bytes must be set to 0). 262 version - cryptoplugin version (CRYPTO_VER(maj,min)). 264 flags - various flags that characterize the cryptoplugin. 266 number_of_algs - number of algorithms the cryptolibrary comprises of 267 (i.e. the number of consequent CryptoAlgInfo structures). 269 3.1.2. Description of CryptoAlgInfo structure 271 Structure fields description 273 status - returns the error code if particular algorithm initialization 274 failed (otherwise should be CRYPTO_OK). 276 id - algorithm identifier (CRYPTO_A_XXX). Values in the range 277 of 0..249 are reserved; Values in the range of 250..32767 278 indicate algorithms not enrolled in standard list. It 279 should be emphasized that algorithm IDs are independent 280 for each algorithm type. But it is considered that pairs 281 of types CRYPTO_TYPE_ENCRYPT and CRYPTO_TYPE_DECRYPT, 282 CRYPTO_TYPE_SIGN and CRYPTO_TYPE_VERIFY, 283 CRYPTO_TYPE_COMPRESS and CRYPTO_TYPE_UNCOMPRESS are 284 equivalent because they define reverse actions of the 285 same nature. 287 group - algorithm implementation group (variants algorithm 288 implementations with various parameters not covered by 289 CryptoAlgInfo structure). Values in the range of 0..32767 290 are well-known numbers defined in Appendix A; vendors may arbitrarily 291 use values in the range of 32768..65535. 293 type - algorithm type (CRYPTO_TYPE_XXX). Unambiguously 294 determines algorithm application. 296 version - version of algorithm implementation (CRYPTO_VER 297 (maj,min)). 299 flags - flags that characterize the algorithm and its 300 implementation. All bits, that are not defined in 301 Appendix A, must be zeroed. 303 maxcontexts - maximum cryptographic contexts number that are 304 simultaneously supported by the algorithm implementation 305 (0 if the number is unlimited or is limited only by 306 environmental conditions like memory size). 308 name - text algorithm name (ASCII characters use only; all 309 unused bytes must be set to 0). 311 The next information depends on algorithm type: 313 For encryption algorithms (CRYPTO_TYPE_ENCRYPT and 314 CRYPTO_TYPE_DECRYPT): 316 blocklen - data block length in bytes (value 1 must be used for 317 stream cipher algorithms). 319 keylen - encrypting (or decrypting) key length in bytes. 321 outlen - output data size for conversion of one input data block 322 in bytes. Usually it is equal to blocklen. When 323 prediction of this value is impossible zero value must be 324 indicated. 326 milen - size of initialization vector (for block algorithms) or 327 message indicator (for stream algorithms) in bytes. For 328 block algorithms zero value of the parameter means that 329 the algorithm implements ECB encoding. Non-zero milen 330 parameter means that the algorithm implements CBC 331 encoding. For stream algorithms zero value of the 332 parameter means that the message indicator is not 333 required. 335 For signature algorithms (CRYPTO_TYPE_SIGN): 337 blocklen - block size in bytes. The length of input signature data 338 will be padded up to this value. When there is no need in 339 padding the value of 1 must be set. 341 keylen - private key length in bytes. 343 outlen - signature length in bytes. When prediction of this value 344 is impossible 0 value must be indicated. If the signature 345 consists of several values then the total length is 346 indicated. 348 milen - non-zero value specifies signature parameter length 349 (random number), zero value indicates that the parameter 350 is not required. 352 For signature verification algorithms (CRYPTO_TYPE_VERIFY): 354 blocklen - is not used. 356 keylen - length of public key in bytes. 358 outlen - signature length in bytes. When prediction of this value 359 is impossible 0 value must be indicated. If the signature 360 consists of several values then the total length is 361 indicated. 363 milen - is not used. 365 For data compression algorithms (CRYPTO_TYPE_COMPRESS): 367 blocklen - see outlen. 369 keylen - is not used. 371 outlen - if the algorithm provides the fixed compression with 372 known value then it is indicated as blocklen/outlen 373 ratio. The values can be arbitrary. If the compression 374 value is not known then outlen is set to 0 and blocklen is 375 not used. 377 milen - is not used. 379 For data uncompressing algorithms (CRYPTO_TYPE_UNCOMPRESS): 381 blocklen - see outlen. 383 keylen - is not used. 385 outlen - if the algorithm provides the fixed compression with 386 known value then it is indicated as blocklen/outlen 387 ratio. The values can be arbitrary. It is natural that 388 the ratio will be reverse to the similar value for the 389 same algorithm but of CRYPTO_TYPE_COMPRESS type. If the 390 compression value is not known then outlen is set to 0 391 and blocklen is not used. 393 milen - is not used. 395 For one-way hash function algorithms (CRYPTO_TYPE_HASH): 397 blocklen - block size in bytes. The length of input data will be 398 padded up to this value. When there is no need in padding 399 value 1 should be used. 401 keylen - is not used. 403 outlen - resulting hash value length in bytes. 405 milen - is not used. 407 For random number generation algorithms (CRYPTO_TYPE_RANDOM): 409 blocklen - is not used. 411 keylen - initial seed length (0 - if not required, for example in 412 a physical effects based generators). 414 outlen - resulting random number length in bytes (0 - arbitrary) 415 milen - is not used. 417 3.2. Cryptoplugin Deinitialization Function 419 /* Plugin deinitialization */ 420 CRYPTO_STATUS CryptoPluginFini(void); 422 The function is called before the cryptoplugin operation is to be 423 terminated. Function execution causes closing of all open cryptographic 424 contexts, system resources deallocation and hardware deinitialization. 425 The value returned is informational only. 427 Return codes for the function: 429 CRYPTO_OK - cryptoplugin is deinitialized successfully. 431 CRYPTO_ERR_GENERAL - internal error. 433 CRYPTO_ERR_UNCLOSED_HANDLES - warning that there were open 434 cryptographic contexts during cryptoplugin 435 deinitialization. The warning is informational only. The 436 open contexts are destroyed anyway. 438 3.3. Cryptographic Context Opening Function 440 /* Get new algorithm instance (cipher state) */ 441 CRYPTO_STATUS CryptoOpen( 442 CRYPTO_HANDLE *state, /* Pointer to cipher state 443 handle (filled on exit) */ 444 long algnum, /* Algorithm number in 445 CryptoPluginInfo structure */ 446 const char *key); /* key (in plain) */ 448 The function creates cryptographic context copy inside cryptoplugin and 449 initializes it with the provided key. Later the handle of the context is 450 used in calls of other algorithm functions. 452 Description of parameters: 454 state - pointer to the variable that will be set to the handle of 455 the context created if succeeded. NULL parameter value 456 should result in the CRYPTO_ERR_BAD_PARAMS code returned 457 by the function. 459 algnum - algorithm number in the cryptoplugin. It is equal to the 460 number of CryptoAlgInfo structure (that describes the 461 algorithm) in CryptoPluginInfo structure. The number 462 begins with zero value. It should be taken into account 463 that it is not an algorithm identifier but its number in 464 the cryptoplugin. 466 key - pointer to the key (if it is required) or to the seed 467 (for random number generation algorithm). 469 Notes. 471 1. Generated cryptographic context is stored inside the cryptoplugin 472 until it will be destroyed by the CryptoAlgClose function call. The 473 maximum number of cryptographic contexts supported by cryptoplugin can 474 be indicated in algorithm parameters description. If maximum number of 475 cryptographic contexts equals to zero then the cryptographic contexts 476 number is either unlimited (for example, for stateless algorithms like 477 random number generators and one-way hash functions) or it is limited 478 by external factors only (like memory size). 480 Return codes for the function: 482 CRYPTO_OK - successful completion. 484 CRYPTO_ERR_GENERAL - internal error. 486 CRYPTO_ERR_NO_RESOURCES - insufficient internal resources. 488 CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general 489 CRYPTO_ERR_NO_RESOURCES error this code assumes that the 490 calling module can release system memory (if it is in 491 position to) and try to call the function once again. 493 CRYPTO_ERR_BAD_PARAMS - invalid parameters (invalid algorithm number, 494 zero pointer to the handle or to key (seed) if it is required. 496 3.4. Cryptographic Context Reopening Function 498 /* Reinitialize algorithm instance */ 499 CRYPTO_STATUS CryptoReOpen( 500 CRYPTO_HANDLE state, /* current cipher state handle */ 501 const char *key); /* key (in plain) */ 503 The function reinitializes an existing context. This function is used 504 for key change without new system resources allocation. The function 505 parameters are handle of opened earlier context and pointer to a new 506 key. 508 Return codes for the function: 510 CRYPTO_OK - successful completion. 512 CRYPTO_ERR_GENERAL - internal error. 514 CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle. 516 CRYPTO_ERR_NO_RESOURCES - insufficient internal resources. 518 CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general 519 CRYPTO_ERR_NO_RESOURCES error this code assumes that the 520 calling module may release system memory and try function 521 call once more. 523 CRYPTO_ERR_BAD_PARAMS - invalid parameters (invalid algorithm number, 524 zero pointer to the handle or to key (seed) if it is required. 526 3.5. Cryptographic Context Closing Function 528 /* Destroy algorithm instance */ 529 CRYPTO_STATUS CryptoClose( 530 CRYPTO_HANDLE state); /* Handle of cipher state */ 532 The function provides cryptographic context destruction. The 533 cryptographic context handle is its parameter. The value returned is 534 informational only. 536 Return codes for the function: 538 CRYPTO_OK - successful completion. 540 CRYPTO_ERR_GENERAL - internal error. 542 CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle. 544 3.6. Key Verification Function 546 /* Check key for possible weakness */ 547 CRYPTO_STATUS CryptoCheckForWeakKey( 548 long algnum, /* Algorithm number in 549 CryptoPluginInfo structure */ 550 const char *key); /* Proposed key */ 552 The function verifies key material whether it is weak (from the 553 algorithm's point of view). The function is actual for 554 encryption/decryption or signing/verification algorithms only. 555 Algorithm number (similar to CryptoAlgOpen) and pointer to the key to 556 be verified are the parameters. 558 Return codes for the function: 560 CRYPTO_O - the key has passed the test. 562 CRYPTO_ERR_WEAK_KEY - the key has not passed the test (being weak 563 or possibly weak). 565 CRYPTO_ERR_NOT_SUPPORTED - is not supported. 567 CRYPTO_ERR_NO_RESOURCES - insufficient internal resources. 569 CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general 570 CRYPTO_ERR_NO_RESOURCES error this code assumes that the 571 calling module can release system memory (if it is in 572 position to) and try to call the function once again. 574 3.7. Data Transformation Function 576 /* Perform CryptoTransform (depends on cipher state type) */ 577 CRYPTO_STATUS CryptoTransform( 578 CRYPTO_HANDLE state, /* Cipher state handle */ 579 const char *inbuff,/* input data */ 580 long inlen, /* input data length */ 581 char *outbuff,/* output buffer */ 582 long *outlen,/* On entry - output buffer 583 length, on exit - number of 584 bytes written to outbuff */ 585 char *mi); /* Message indicator */ 587 This is a cryptographic data transformation function. Function call 588 results and function parameters are dependent on algorithm type. For 589 algorithm types CRYTO_TYPE_ENCRYPT, CRYPTO_TYPE_DECRYPT, 590 CRYPTO_TYPE_SIGN and CRYPTO_TYPE_VERIFY (items 3.7.1 - 3.7.4) function 591 call results are history independent. 593 Note. Stream encryption algorithms may seem an "exception". However the 594 same cryptoalgorithm handle must hide its history dependence. For 595 algorithm types CRYPTO_TYPE_COMPRESS, CRYPTO_TYPE_UNCOMPRESS and 596 CRYPTO_TYPE_HASH (items 3.7.5 - 3.7.7) function calls are history 597 dependent. For the CRYPTO_TYPE_RANDOM algorithm function call may be 598 for different implementations either dependent or independent on the 599 history. 601 3.7.1. For CRYPTO_TYPE_ENCRYPT Algorithm Type: 603 The function encrypts input data. Its parameters are intended for: 605 inbuff - pointer to the input data. If this parameter is equal to 606 NULL then the function should return the 607 CRYPTO_ERR_BAD_PARAMS error code. 609 inlen - input data size (in bytes). If the size indicated in 610 algorithm description is divisible by blocklen then 611 padding is not carried out. Otherwise the algorithm 612 either caries out padding according to the algorithm 613 standard or returns appropriate error code 614 (CRYPTO_ERR_BAD_PARAMS). The zero parameter is allowed so 615 that the function quits at once and returns CRYPTO_OK 616 code. 618 outbuff - output data buffer. NULL parameter value results in the 619 outlen parameter setting to output buffer size required 620 to encrypt the input buffer represented. In this case the 621 CRYPTO_ERR_SMALL_BUFFER error should not be returned. 623 outlen - Output buffer size is an input function parameter while 624 the number of bytes written in the output buffer is the 625 output parameter. Both the NULL parameter value and the 626 zero value addressed result in CRYPTO_ERR_BAD_PARAMS code 627 returned by the function. 629 mi - message indicator. Its content depends on whether the 630 block or stream algorithm is applied. In the block 631 algorithm case it is set to the last block encrypted. 632 When the first block is encrypted mi parameter specifies 633 initial initialization vector. In the stream algorithm 634 case it is set to the offset of the first byte encrypted 635 in the stream. If the algorithm uses the message 636 indicator and the mi parameter value is set to NULL then 637 function should return CRYPTO_ERR_BAD_PARAMS. If the 638 algorithm (ECB Mode encrypting as an example) does not 639 apply the message indicator then NULL value of mi is 640 acceptable while non-NULL value should be ignored. 642 Returned values: 644 CRYPTO_OK - successful completion. 646 CRYPTO_ERR_GENERAL - internal error. 648 CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle. 650 CRYPTO_ERR_NO_RESOURCES - insufficient internal resources. 652 CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general 653 CRYPTO_ERR_NO_RESOURCES error this code assumes that the 654 calling module can release system memory (if it is in 655 position to) and try to call the function once again. 657 CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size. 659 CRYPTO_ERR_BAD_PARAMS - invalid parameters. 661 3.7.2. For CRYPTO_TYPE_DECRYPT Algorithm Type: 663 The function decrypts the input data. Its parameters are intended for: 665 inbuff - pointer to the input data. If the parameter is equal to 666 NULL then the function should return the 667 CRYPTO_ERR_BAD_PARAMS error code. 669 inlen - input data size (in bytes). When the parameter is set to 670 zero the function quits at once and CRYPTO_OK code is 671 returned. 673 outbuff - output data buffer. NULL parameter value results in the 674 outlen parameter setting to output buffer size required 675 to decrypt the input buffer represented. In this case the 676 CRYPTO_ERR_SMALL_BUFFER error should not be returned. 678 outlen - Output buffer size is an input function parameter while 679 the number of bytes written in the output buffer is the 680 output parameter. Both the NULL parameter value and the 681 zero value addressed result in CRYPTO_ERR_BAD_PARAMS code 682 returned by the function. 684 mi - message indicator. The content depends on whether the 685 block or stream algorithm is applied. In the block 686 algorithm case it is set to the last block encrypted. 687 When the first block is decrypted mi specifies initial 688 initialization vector. In the stream algorithm case it is 689 set to the offset of the first byte decrypted in the 690 stream. If the algorithm uses the message indicator and 691 the mi parameter is set to NULL then function should 692 return CRYPTO_ERR_BAD_PARAMS. If the algorithm (ECB Mode 693 as an example) does not apply the message indicator then 694 NULL value of mi is acceptable while non-NULL value 695 should be ignored. 697 Returned values: 699 CRYPTO_OK - successful completion. 701 CRYPTO_ERR_GENERAL - internal error. 703 CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle. 705 CRYPTO_ERR_NO_RESOURCES - insufficient internal resources. 707 CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general 708 CRYPTO_ERR_NO_RESOURCES error this code assumes that the 709 calling module can release system memory (if it is in 710 position to) and try to call the function once again. 712 CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size. 714 CRYPTO_ERR_BAD_PARAMS - invalid parameters. 716 3.7.3. For CRYPTO_TYPE_SIGN Type Algorithm: 718 The function signs the input data. Its parameters are intended for: 720 inbuff - pointer to the input data. If the parameter is equal to 721 NULL then the function should return the 722 CRYPTO_ERR_BAD_PARAMS code error. 724 inlen - input data size (in bytes). If the size indicated in 725 algorithm description is divisible by blocklen then 726 padding is not carried out. Otherwise the algorithm 727 either caries out padding according to the algorithm 728 standard or returns appropriate error code 729 (CRYPTO_ERR_BAD_PARAMS). The zero parameter is allowed so 730 that the function quits at once and returns CRYPTO_OK 731 code. 733 outbuff - output data buffer. NULL parameter value results in the 734 outlen parameter setting to output buffer size required 735 to sign the input buffer represented. In this case the 736 CRYPTO_ERR_SMALL_BUFFER error should not be returned. 738 outlen - Output buffer size is an input function parameter while 739 the number of bytes written in the output buffer is the 740 output parameter. Both the NULL parameter value and the 741 zero value addressed result in CRYPTO_ERR_BAD_PARAMS code 742 returned by the function. 744 mi - pointer to signature parameter (random number usually) if 745 milen parameter in algorithm description is non-zero. In 746 this case zero mi parameter indicates that the parameter 747 should be chosen (generated) inside the algorithm. If 748 milen parameter in algorithm description is set to zero 749 then mi parameter is ignored. 751 Returned values: 753 CRYPTO_OK - successful completion. 755 CRYPTO_ERR_GENERAL - internal error. 757 CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle. 759 CRYPTO_ERR_NO_RESOURCES - insufficient internal resources. 761 CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general 762 CRYPTO_ERR_NO_RESOURCES error this code assumes that the 763 calling module can release system memory (if it is in 764 position to) and try to call the function once again. 766 CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size. 768 CRYPTO_ERR_BAD_PARAMS - invalid parameters. 770 3.7.4. For CRYPTO_TYPE_VERIFY Algorithm Type: 772 The function verifies input data signature. Its parameters are intended 773 for: 775 inbuff - pointer to the input data. If the parameter is equal to 776 NULL then the function should return the 777 CRYPTO_ERR_BAD_PARAMS code error. 779 inlen - input data size (in bytes). The zero parameter is allowed 780 so that the function quits at once and returns CRYPTO_OK 781 code. 783 outbuff -pointer to the signature. If the parameter is set to NULL 784 then the function returns CRYPTO_ERR_BAD_PARAMS error 785 code. If the signature consists of several parts then 786 they are combined to one array. 788 outlen - specifies the signature length if the signature length is 789 set to zero in algorithm description structure. If 790 non-zero value is specified in algorithm description 791 structure then the parameter is ignored. If the signature 792 consists of several parts then the maximum part length 793 multiplied by the number of parts is specified. 795 mi - is not used. 797 Returned values: 799 CRYPTO_OK - successful completion. 801 CRYPTO_ERR_INVALID_SIGNATURE - invalid signature. 803 CRYPTO_ERR_GENERAL - internal error. 805 CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle. 807 CRYPTO_ERR_NO_RESOURCES - insufficient internal resources. 809 CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general 810 CRYPTO_ERR_NO_RESOURCES error this code assumes that the 811 calling module can release system memory (if it is in 812 position to) and try to call the function once again. 814 CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size. 816 CRYPTO_ERR_BAD_PARAMS - invalid parameters. 818 3.7.5. For CRYPTO_TYPE_COMPRESS Algorithm Type: 820 The function compresses the input data. Its parameters are intended for: 822 inbuff - pointer to the input data. 824 inlen - input data size (in bytes). The zero parameter is allowed 825 so that the function quits at once and returns CRYPTO_OK 826 code. 828 outbuff - output data buffer. NULL parameter value results in the 829 outlen parameter setting to output buffer size required 830 to compress the input buffer represented. In this case 831 the CRYPTO_ERR_SMALL_BUFFER error should not be returned. 833 outlen - Output buffer size is an input function parameter while 834 the number of bytes written in the output buffer is the 835 output parameter. Both the NULL parameter value and the 836 zero value addressed result in CRYPTO_ERR_BAD_PARAMS code 837 returned by the function. 839 mi - is not used. 841 Returned values: 843 CRYPTO_OK - successful completion. 845 CRYPTO_ERR_GENERAL - internal error. 847 CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle. 849 CRYPTO_ERR_NO_RESOURCES - insufficient internal resources. 851 CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general 852 CRYPTO_ERR_NO_RESOURCES error this code assumes that the 853 calling module can release system memory (if it is in 854 position to) and try to call the function once again. 856 CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size. 858 CRYPTO_ERR_BAD_PARAMS - invalid parameters. 860 3.7.6. For CRYPTO_TYPE_UNCOMPRESS Algorithm Type: 862 The function decompresses the input data. Its parameters are intended 863 for: 865 inbuff - pointer to the input data. 867 inlen - input data size (in bytes). The zero parameter is allowed 868 so that the function quits at once and returns CRYPTO_OK 869 code. 871 outbuff - output data buffer. NULL parameter value results in the 872 outlen parameter setting to output buffer size required 873 to decompress the input buffer represented. In this case 874 the CRYPTO_ERR_SMALL_BUFFER error should not be returned. 876 outlen - Output buffer size is an input function parameter while 877 the number of bytes written in the output buffer is the 878 output parameter. Both the NULL parameter value and the 879 zero value addressed result in CRYPTO_ERR_BAD_PARAMS code 880 returned by the function. 882 mi - is not used. 884 Returned values: 886 CRYPTO_OK - successful completion. 888 CRYPTO_ERR_GENERAL - internal error. 890 CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle. 892 CRYPTO_ERR_NO_RESOURCES - insufficient internal resources. 894 CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general 895 CRYPTO_ERR_NO_RESOURCES error this code assumes that the 896 calling module can release system memory (if it is in 897 position to) and try to call the function once again. 899 CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size. 901 CRYPTO_ERR_BAD_PARAMS - invalid parameters. 903 3.7.7. For CRYPTO_TYPE_HASH Algorithm Type: 905 The function calculates the hash value of the input data. Its 906 parameters are intended for: 908 inbuff - pointer to the input data. If the parameter is of NULL 909 value then the function calculates cumulative hash value 910 for the data represented (taking into account all 911 previous data represented). If total length of all the 912 data represented by the moment is divisible by blocklen 913 and outbuff is non-NULL then it is returned to outbuff. 914 Nothing is written in outbuff when the length is not 915 divisible by blocklen. NULL inbuff indicates the last 916 conversion when the input data is padded up to the 917 blocklen size and the result is written to outbuff 918 address. The padding procedure is defined for the 919 algorithm. 921 inlen - input data size (in bytes). The zero parameter is allowed 922 when the function quits at once and returns CRYPTO_OK 923 code. 925 outbuff - output data buffer. 927 outlen - Output buffer size is an input function parameter while 928 the number of bytes written in the output buffer is the 929 output parameter. If intermediate conversion value 930 (inbuff is not NULL) and total length of data represented 931 by the moment are not divisible by blocklen then outlen 932 is set to zero and the hash value is not written in 933 outbuff. Both the NULL parameter value and the zero value 934 addressed result in CRYPTO_ERR_BAD_PARAMS code returned 935 by the function. 937 mi - is not used. 939 Returned values: 941 CRYPTO_OK - successful completion. 943 CRYPTO_ERR_GENERAL - internal error. 945 CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle. 947 CRYPTO_ERR_NO_RESOURCES - insufficient internal resources. 949 CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general 950 CRYPTO_ERR_NO_RESOURCES error this code assumes that the 951 calling module can release system memory (if it is in 952 position to) and try to call the function once again. 954 CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size. 956 CRYPTO_ERR_BAD_PARAMS - invalid parameters. 958 3.7.8. For CRYPTO_TYPE_RANDOM Algorithm Type: 960 The function generates a random number. Its parameters are intended 961 for: 963 inbuff - pointer to the input data used for generation (when one 964 of the pseudorandom algorithms is implemented). NULL 965 parameter indicates absence of the input data. 967 inlen - input data size (in bytes). 969 outbuff - output data buffer. 971 outlen - Output buffer size is an input function parameter while 972 the number of bytes written in the output buffer is the 973 output parameter. If zero (i.e. arbitrary) generated 974 number size is set in the algorithm description then the 975 outlen value determines the number of random bytes 976 required by the calling procedure. 978 mi - is not used. 980 Returned values: 982 CRYPTO_OK - successful completion. 984 CRYPTO_ERR_GENERAL - internal error. 986 CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle. 988 CRYPTO_ERR_NO_RESOURCES - insufficient internal resources. 990 CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general 991 CRYPTO_ERR_NO_RESOURCES error this code assumes that the 992 calling module can release system memory (if it is in 993 position to) and try to call the function once again. 995 CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size. 997 CRYPTO_ERR_BAD_PARAMS - invalid parameters. 999 3.8. Cryptographic Context Control Function 1001 /* Algorithm control */ 1002 CRYPTO_STATUS CryptoControl( 1003 CRYPTO_HANDLE state, /* Cipher state handle */ 1004 long cmd, /* Control command */ 1005 long param, /* Parameter id */ 1006 char val, /* Parameter value */ 1007 long *len); /* For CRYPTO_GET: on entry - 1008 val buffer length, on exit - 1009 number of bytes written to 1010 val; for CRYPTO_SET: length 1011 of value to set */ 1013 The function provides cryptographic context internal parameters 1014 management. It may be used to check context parameters or to change the 1015 context state, for example it may return information about 1016 cryptoalgorithm (is given context uses hardware encryption facilities), 1017 or it may "scroll" stream algorithms context if necessary, etc. 1019 Description of parameters: 1021 state - cryptographic context handle. 1023 cmd - command (CRYPTO_GET or CRYPTO_SET). 1025 param - identifier of parameter. Values in the range of 0..32767 1026 are assigned well-known numbers for all algorithms. 1027 Values in the range of 32768..65535 mean various 1028 variables for various algorithms (may be arbitrarily used 1029 by cryptolibrary developer). 1031 val - pointer to the data buffer. 1033 len - data size (in bytes). 1035 Returned values: 1037 CRYPTO_OK - successful completion. 1039 CRYPTO_ERR_GENERAL - internal error. 1041 CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle. 1043 CRYPTO_ERR_NO_RESOURCES - insufficient internal resources. 1045 CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general 1046 CRYPTO_ERR_NO_RESOURCES error this code assumes that the 1047 calling module can release system memory (if it is in 1048 position to) and try to call the function once again. 1050 CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size. 1052 CRYPTO_ERR_BAD_PARAMS - invalid parameters. 1054 4. Cryptoplugin Registration Procedure 1056 Cryptoplugin should be linked together with the cryptoplugin wrapper 1057 library delivered by the cryptoplugin's client developer according to 1058 the rules specified by the module-client developer for each platform. 1059 It should result in a driver (module) of appropriate operating system 1060 that implements the cryptolibrary functions. The driver should be one 1061 of the drivers loaded during operating system boot. The procedure of 1062 �ryptoplugin driver installation should be defined, documented, and 1063 automated when necessary, by the cryptoplugin developer. At the 1064 beginning of operation the driver-client determines cryptoplugin driver 1065 availability and establishes interconnection with it. Both 1066 module-client configuration and current security policy determine data 1067 conversion algorithms to be chosen. 1069 5. Security Considerations 1071 Security issues are not addressed in this memo. 1073 6. References 1075 [Schneier] Bruce Schneier, Applied Cryptography - Protocols, 1076 Algorithms, and Source Code in C (Second Edition), John 1077 Wiley & Sons, Inc., 1996. 1079 [IPsec] Kent, S., and R. Atkinson, "Security Architecture for the 1080 Internet Protocol", RFC 2401, November 1998. 1082 [ISAKMP] Maughhan, D., Schertler, M., Schneider, M., and J. Turner, 1083 "Internet Security Association and Key Management Protocol 1084 (ISAKMP)", RFC 2408, November 1998. 1086 [IKE] Harkins, D. and Carrel, D., "The Internet Key Exchange 1087 (IKE)", RFC2409, November 1998. 1089 [TLS] Dierks, T. and Allen, C., "The TLS protocol Version 1.0", 1090 RFC2246, January 1999. 1092 7. Author's Address 1094 Valery Smyslov 1095 TWS 1096 Centralny prospekt,11, Moscow, Russia 1097 Phone: +7 (095) 531 4633 1098 Fax: +7 (095) 531 2403 1099 Email:svan@trustworks.com 1101 Appendix A. The interface specification as a C header file 1103 #ifndef __CRYPTPI_H 1104 #define __CRYPTPI_H 1106 #define CRYPTO_VER(maj,min) (((maj & 0xff) << 8) | (min & 0xff)) 1107 #define CRYPTO_MAJ_VER(ver) ((ver >> 8) & 0xff) 1108 #define CRYPTO_MIN_VER(ver) (ver & 0xff) 1110 #define CRYPTO_PLUGIN_NAME_LEN 64 /* Must be multiple of 4 to */ 1111 #define CRYPTO_ALG_NAME_LEN 32 /* avoid alignment problems */ 1113 #ifndef CRYPTO_HANDLE 1114 #define CRYPTO_HANDLE void* /* cipher state handle */ 1115 #endif 1117 typedef enum tag_CRYPTO_STATUS { 1118 CRYPTO_OK = 1, /* success */ 1119 CRYPTO_ERR_GENERAL, /* undefined (internal) error */ 1120 CRYPTO_ERR_NOT_SUPPORTED, /* unsupported */ 1121 CRYPTO_ERR_BAD_HANDLE, /* invalid handle */ 1122 CRYPTO_ERR_SMALL_BUFFER, /* insufficient output buffer 1123 size */ 1124 CRYPTO_ERR_WEAK_KEY, /* key is considered to be weak 1125 (semiweak, pseudoweak) */ 1126 CRYPTO_ERR_NO_RESOURCES, /* insufficient resources to 1127 perform operation */ 1128 CRYPTO_ERR_NO_MEMORY, /* insufficient memory to 1129 perform operation */ 1130 CRYPTO_ERR_BAD_PARAMS, /* invalid parameters */ 1131 CRYPTO_ERR_HARDWARE, /* hardware error */ 1132 CRYPTO_ERR_INVALID_SIGNATURE, /* invalid signature */ 1133 CRYPTO_ERR_UNCLOSED_HANDLES /* unclosed handles exist while 1134 plugin deinitializises */ 1135 } CRYPTO_STATUS; 1137 /* CryptoControl commands */ 1138 #define CRYPTO_GET 1 /* get parameter */ 1139 #define CRYPTO_SET 2 /* set parameter */ 1141 /* Currently defined algorithm types */ 1142 #define CRYPTO_TYPE_ENCRYPT 1 1143 #define CRYPTO_TYPE_DECRYPT 2 1144 #define CRYPTO_TYPE_SIGN 3 1145 #define CRYPTO_TYPE_VERIFY 4 1146 #define CRYPTO_TYPE_COMPRESS 5 1147 #define CRYPTO_TYPE_UNCOMPRESS 6 1148 #define CRYPTO_TYPE_HASH 7 1149 #define CRYPTO_TYPE_RANDOM 8 1150 /* Currently defined algorithm IDs (for types 1151 CRYPTO_TYPE_ENCRYPT & CRYPTO_TYPE_DECRYPT) */ 1152 #define CRYPTO_AE_DUMMY 1 /* no encryption */ 1153 #define CRYPTO_AE_DES 2 /* DES-CBC */ 1154 #define CRYPTO_AE_3DES_EDE 3 /* Triple DES-EDE-CBC */ 1155 #define CRYPTO_AE_IDEA 4 /* IDEA-CBC */ 1156 #define CRYPTO_AE_RC2 5 /* RC2 */ 1157 #define CRYPTO_AE_RC4 6 /* RC4 */ 1158 #define CRYPTO_AE_RC5 7 /* RC5 */ 1159 #define CRYPTO_AE_SAFER 8 /* SAFER */ 1160 #define CRYPTO_AE_CAST 9 /* CAST */ 1161 #define CRYPTO_AE_BLOWFISH 10 /* Blowfish */ 1162 #define CRYPTO_AE_RSA 11 /* RSA */ 1163 #define CRYPTO_AE_GOST 12 /* GOST */ 1165 /* Currently defined algorithm IDs (for types 1166 CRYPTO_TYPE_SIGN & CRYPTO_TYPE_VERIFY) */ 1167 #define CRYPTO_AS_RSA 2 /* RSA */ 1168 #define CRYPTO_AS_DSA 3 /* DSA */ 1169 #define CRYPTO_AS_GOST 4 /* GOST */ 1171 /* Currently defined algorithm IDs (for types 1172 CRYPTO_TYPE_COMPRESS & CRYPTO_TYPE_UNCOMPRESS) */ 1173 #define CRYPTO_AC_DUMMY 1 /* no compression */ 1174 #define CRYPTO_AC_DEFLATE 2 /* Deflate */ 1175 #define CRYPTO_AC_LZS 3 /* LZS */ 1177 /* Currently defined algorithm IDs (for type CRYPTO_TYPE_HASH) */ 1178 #define CRYPTO_AH_MD5 1 /* MD5 */ 1179 #define CRYPTO_AH_SHA 2 /* SHA-1 */ 1180 #define CRYPTO_AH_GOST 3 /* GOST */ 1182 /* Currently defined algorithm IDs (for type CRYPTO_TYPE_RANDOM) */ 1183 #define CRYPTO_AR_UNKNOWN 1 1185 /* Currently defined plugin flags */ 1186 #define CRYPTO_PLUGIN_HARDWARE 1 /* plugin uses hdw */ 1187 /* TBD more */ 1189 /* Currently defined algorithm flags */ 1190 #define CRYPTO_ALG_HARDWARE 1 /* algorithm implemented 1191 in hardware */ 1192 #define CRYPTO_ALG_MULTITHREADED 2 /* implementation allows 1193 multithreading */ 1194 /* TBD more */ 1196 /* Currently defined parameters identifiers for CryptoControl */ 1197 #define CRYPTO_PARAM_KEY 1 /* Only for CRYPTO_GET - 1198 get current key */ 1199 /* TBD more */ 1200 typedef struct tag_CryptoAlgInfo { 1201 long status; /* Algorithm status */ 1202 long type; /* algorithm type (One of 1203 CRYPTO_TYPE_XXX) */ 1204 long id; /* algorithm ID */ 1205 long group; /* algorithm group */ 1206 long version; /* algorithm version 1207 (CRYPTO_VER) */ 1208 long flags; /* algorithm flags 1209 (CRYPTO_ALG_XXX) */ 1210 long maxcontexts; /* max number of cipher states 1211 supported (0 - any) */ 1212 char name[CRYPTO_ALG_NAME_LEN]; /* algorithm name */ 1213 /* CRYPT SIGN COMPRESS HASH RANDOM */ 1214 /* DECRYPT VERIFY */ 1215 long blocklen; /* blklen (blklen) inlen blklen - */ 1216 long keylen; /* keylen keylen - - seedlen */ 1217 long outlen; /* outlen (signlen) outlen hashlen randlen */ 1218 long milen; /* milen (param) - - - */ 1219 } CryptoAlgInfo; 1221 typedef struct tag_CryptoPluginInfo { 1222 long cpi_version; /* Crypto PI version (currently 1223 CRYPTO_VER(1,0)) */ 1224 long status; /* Plugin status */ 1225 char name[CRYPTO_PLUGIN_NAME_LEN]; /* plugin text 1226 description */ 1227 long version; /* plugin version 1228 (CRYPTO_VER) */ 1229 long flags; /* plugin flags 1230 (CRYPTO_PLUGIN_XXX) */ 1231 long number_of_algs; /* number of AlgInfo structures 1232 followed (min 1) */ 1233 CryptoAlgInfo algs[1]; /* array of AlgInfo structures 1234 (min 1) */ 1235 } CryptoPluginInfo; 1237 #ifdef __cplusplus 1238 extern "C" { 1239 #endif 1241 /* CryptoPlugin initialization. Returns pointer to CryptoPluginInfo 1242 structure on success or NULL on fatal error. */ 1243 CryptoPluginInfo *CryptoPluginInit( 1244 void *param);/* Ptr to OS parameters 1245 (platform-specific) */ 1247 /* Plugin deinitialization */ 1248 CRYPTO_STATUS CryptoPluginFini(void); 1250 /* Get new algorithm instance (cipher state) */ 1251 CRYPTO_STATUS CryptoOpen( 1252 CRYPTO_HANDLE *state, /* Pointer to cipher state 1253 handle (filled on exit) */ 1254 long algnum, /* Algorithm number in 1255 CryptoPluginInfo structure */ 1256 const char *key); /* key (in plain) */ 1258 /* Reinitialize algorithm instance */ 1259 CRYPTO_STATUS CryptoReOpen( 1260 CRYPTO_HANDLE state, /* current cipher state handle */ 1261 const char *key); /* key (in plain) */ 1263 /* Destroy algorithm instance */ 1264 CRYPTO_STATUS CryptoClose( 1265 CRYPTO_HANDLE state); /* Handle of cipher state */ 1267 /* Check key for possible weakness */ 1268 CRYPTO_STATUS CryptoCheckForWeakKey( 1269 long algnum, /* Algorithm number in 1270 CryptoPluginInfo structure */ 1271 const char *key); /* Proposed key */ 1273 /* Perform CryptoTransform (depends on cipher state type) */ 1274 CRYPTO_STATUS CryptoTransform( 1275 CRYPTO_HANDLE state, /* Cipher state handle */ 1276 const char *inbuff,/* input data */ 1277 long inlen, /* input data length */ 1278 char *outbuff,/* output buffer */ 1279 long *outlen,/* On entry - output buffer 1280 length, on exit - number of 1281 bytes written to outbuff */ 1282 char *mi); /* Message indicator */ 1284 /* Algorithm control */ 1285 CRYPTO_STATUS CryptoControl( 1286 CRYPTO_HANDLE state, /* Cipher state handle */ 1287 long cmd, /* Control command */ 1288 long param, /* Parameter id */ 1289 char val, /* Parameter value */ 1290 long *len); /* For CRYPTO_GET: on entry - 1291 val buffer length, on exit - 1292 number of bytes written to 1293 val; for CRYPTO_SET: length 1294 of value to set */ 1296 #ifdef __cplusplus 1297 } 1298 #endif 1300 #endif /* __CRYPTPI_H */