File: rfc2628.txt

package info (click to toggle)
doc-rfc 20181229-2
  • links: PTS, VCS
  • area: non-free
  • in suites: buster
  • size: 570,944 kB
  • sloc: xml: 285,646; sh: 107; python: 90; perl: 42; makefile: 14
file content (1683 lines) | stat: -rw-r--r-- 60,070 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683






Network Working Group                                         V. Smyslov
Request for Comments: 2628                                           TWS
Category: Informational                                        June 1999


          Simple Cryptographic Program Interface (Crypto API)

Status of this Memo

   This memo provides information for the Internet community.  It does
   not specify an Internet standard of any kind.  Distribution of this
   memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (1999).  All Rights Reserved.

Abstract

   This document describes a simple Application Program Interface to
   cryptographic functions. The main purpose of such an interface is to
   separate cryptographic libraries from internet applications, thus
   allowing an independent development of both. It can be used in
   various internet applications such as [IPsec], [ISAKMP], [IKE],
   [TLS].

Table of Contents

   1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . .  2
   1.1. Summary . . . . . . . . . . . . . . . . . . . . . . . . . . .  2
   1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . .  2
   1.3. Objectives of Development . . . . . . . . . . . . . . . . . .  3
   2. Cryptoplugin Structure. . . . . . . . . . . . . . . . . . . . .  3
   3. Program Interface . . . . . . . . . . . . . . . . . . . . . . .  4
   3.1. Cryptoplugin Initialization Function. . . . . . . . . . . . .  4
   3.1.1. Description of CryptoPluginInfo structure . . . . . . . . .  6
   3.1.2. Description of CryptoAlgInfo structure. . . . . . . . . . .  6
   3.2. Cryptoplugin Deinitialization Function. . . . . . . . . . . .  9
   3.3. Cryptographic Context Opening Function. . . . . . . . . . . . 10
   3.4. Cryptographic Context Reopening Function. . . . . . . . . . . 11
   3.5. Cryptographic Context Closing Function. . . . . . . . . . . . 12
   3.6. Key Verification Function . . . . . . . . . . . . . . . . . . 12
   3.7. Data Transformation Function. . . . . . . . . . . . . . . . . 13
   3.7.1. For CRYPTO_TYPE_ENCRYPT Algorithm Type. . . . . . . . . . . 13
   3.7.2. For CRYPTO_TYPE_DECRYPT Algorithm Type. . . . . . . . . . . 14
   3.7.3. For CRYPTO_TYPE_SIGN Algorithm Type . . . . . . . . . . . . 15
   3.7.4. For CRYPTO_TYPE_VERIFY Algorithm Type . . . . . . . . . . . 17
   3.7.5. For CRYPTO_TYPE_COMPRESS Algorithm Type . . . . . . . . . . 18



Smyslov                      Informational                      [Page 1]

RFC 2628                       Crypto API                      June 1999


   3.7.6. For CRYPTO_TYPE_UNCOMPRESS Algorithm Type . . . . . . . . . 18
   3.7.7. For CRYPTO_TYPE_HASH Algorithm Type . . . . . . . . . . . . 19
   3.7.8. For CRYPTO_TYPE_RANDOM Algorithm Type.  . . . . . . . . . . 21
   3.8. Cryptographic Context Control Function. . . . . . . . . . . . 22
   4. Cryptoplugin Registration Procedure . . . . . . . . . . . . . . 23
   5. Security Considerations . . . . . . . . . . . . . . . . . . . . 23
   6. References. . . . . . . . . . . . . . . . . . . . . . . . . . . 23
   7. Author's Address  . . . . . . . . . . . . . . . . . . . . . . . 24
   Appendix A. The interface specification as a C header file . . . . 25
   Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 30

1. Introduction

1.1. Summary

   Nowadays internet applications that require cryptographic functions
   at the level of operating system kernel, use the method that assumes
   the libraries must be compiled/linked together with the module
   (driver) which provides product functionality. For the sake of
   possibility of independent development of the cryptographic modules
   and in order to provide a simple, effective and universal (suitable
   for application and as well kernel level of operating system)
   solution this specification offers the method to extract encrypting
   algorithms to the separate cryptographic modules.

   This document describes simple open interface (Crypto API) to
   external cryptographic libraries optimized both for the application
   and kernel level of the operating system.

1.2. Terminology

   Cryptoplugin

      Operation system unit (driver, shared library, module) that
      provides cryptographic functions via well-defined (but OS-
      specific) interface.

   Cryptolibrary

      Part of cryptoplugin that provides its cryptographic functionality
      via Crypto API.

   Wrapper

      Part of cryptoplugin that provides interfaces translation between
      Crypto API and OS-specific interface.





Smyslov                      Informational                      [Page 2]

RFC 2628                       Crypto API                      June 1999


   Definition of all cryptography related terms can be found in
   [Schneier].

1.3. Objectives of Development

   The objectives of Simple CryptoAPI development are as follows:

      1) To extract program implementations of encryption, one-way hash
         function, digital signature and random numbers generation
         algorithms to separate, independently developed modules.

      2) To provide version independence between using encryption
         modules and external cryptoplugin.

      3) To ensure platform independent developments of encrypting
         algorithm modules with portable source code.

      4) To enable independent development of modules and compatibility
         of modules developed independently.

2. Cryptoplugin Structure

   In order to provide fast exchange between the cryptoplugin and its
   client the cryptoplugin is implemented as a separate driver (or
   module) of the particular operating system (Fig.1). Cryptoplugin
   consists of two parts (Fig.2):

      1) cryptolibrary itself (1)

      2) system-dependent module (wrapper) for interaction between
         cryptolibrary and its client (2)

                                       Cryptoplugin initialization
                                     / by the operating system
                                     |
                                     |
     +------------------+          +-|-+-------------+
     |                  |          |   |             |
     |  Cryptoplugin's  | -------> |                 |
     |                  |          |  Cryptoplugin   |
     |     client       | <------- |                 |
     |                  |          |   |             |
     +------------------+     |    +---+-------------+
                              |
                              \
                               \ System-dependent CPI

    Fig. 1  Interaction between cryptoplugin and its client



Smyslov                      Informational                      [Page 3]

RFC 2628                       Crypto API                      June 1999


     +---------------+-------------------------------+
     |               |                               |
     |              -->       Submodule of           |
     |  Submodule -  |                               |
     |               |   encrypting algorithms (1)   |
     |  wrapper (2)  |                               |
     |              <--       (cryptolibrary)        |
     |               |                               |
     +---------------+-------------------------------+
                     |
                     \
                      \ Cryptographic Program Interface

                Fig. 2  Cryptoplugin structure

   The system-dependent module (wrapper) is delivered by the driver-
   client developer in the form of source code or in the form of
   libraries (for example, in the form of object files) for particular
   operating system.  The wrapper is intended for translation of
   system-independent application interface to the particular system-
   dependent interface with the cryptoplugin's client. The wrapper
   context does not include components specific to cryptoplugin's client
   functionality or to some cryptographic algorithm. The interface
   described in section 3 is the standard for interaction between the
   submodules (1) and (2).

   A cryptoplugin can contain a number of different algorithms.
   Moreover, it can contain some different implementations of one
   particular algorithm.

3. Program Interface

   The CPI (Cryptographic Program Interface) consists of a set of
   functions exported by encrypting algorithm submodule (cryptolibrary).
   The interface functions are described below (see also Appendix A).

3.1. Cryptoplugin Initialization Function

   The function is intended for cryptoplugin initialization and
   obtaining information about algorithms contained in cryptoplugin. The
   function is called once before the beginning of cryptoplugin
   operation.

   /* CryptoPlugin initialization. Returns pointer to CryptoPluginInfo
   structure on success or NULL on fatal error. */
   CryptoPluginInfo *CryptoPluginInit(
                   void            *param);/* Ptr to OS parameters
                                              (platform-specific) */



Smyslov                      Informational                      [Page 4]

RFC 2628                       Crypto API                      June 1999


   Description of parameters:

      param - pointer to system-dependent parameters transmitted to
         cryptoplugin by the operating system. Intention and format of
         parameters are specific to each operating system and should be
         described in documentation on the cryptoplugin wrapper.

   The function is called at the moment of cryptoplugin initialization.
   If succeeded it returns the pointer to CryptoPluginInfo structure
   that describes the module and algorithms implemented in the
   cryptolibrary.  If function call did not succeed, function will
   return NULL or appropriate error code in CryptoPluginInfo structure
   status field. If the initialization is partially succeeded then the
   cryptoplugin either returns CryptoPluginInfo structure transformed so
   that it contains only successfully initialized algorithms or returns
   appropriate error code in status field of CryptoAlgInfo structures
   that describes the reason for the failure.

   Error codes for the function:

      NULL - fatal unsuccessful cryptoplugin initialization. The module
         is unable even to indicate the reason of failure.

   The pointer to cryptoplugin description structure in the case of full
   or partial success. The status fields in CryptoPluginInfo structure
   and in comprised CryptoAlgInfo structures can be set to the following
   values:

      CRYPTO_OK - cryptoplugin (algorithm) is initialized successfully.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_NOT_SUPPORTED - (only for algorithm) - the algorithm
         is not supported by the module at the moment.

      CRYPTO_ERR_HARDWARE - error of hardware initialization.

      CRYPTO_ERR_NO_RESOURCES - insufficient internal resources.

      CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general
         CRYPTO_ERR_NO_RESOURCES error this code assumes that the
         calling module can release system memory (if it is in position
         to) and try to call the function once again.








Smyslov                      Informational                      [Page 5]

RFC 2628                       Crypto API                      June 1999


3.1.1. Description of CryptoPluginInfo structure

   The CryptoPluginInfo structure consists of header of fixed size that
   generally describes cryptoplugin and array of CryptoAlgInfo
   structures following the header. Each structure describes particular
   algorithm implemented in the cryptolibrary (see Appendix A)

   Structure fields description:

      cpi_version -  CPI version (should be CRYPTO_VER (1,0)). CPI
         version determines both functions set and fields layout in
         CryptoPluginInfo/CryptoAlgInfo structures.

      status - returns the error code if cryptoplugin initialization
         failed (otherwise should be CRYPTO_OK)

      name - text cryptoplugin description (ASCII-7 characters only; all
         unused bytes must be set to 0).

      version - cryptoplugin version (CRYPTO_VER(maj,min)).

      flags - various flags that characterize the cryptoplugin.

      number_of_algs - number of algorithms the cryptolibrary comprises
         of (i.e. the number of consequent CryptoAlgInfo structures).

3.1.2. Description of CryptoAlgInfo structure

   Structure fields description

      status - returns the error code if particular algorithm
         initialization failed (otherwise should be CRYPTO_OK).

      id - algorithm identifier (CRYPTO_A_XXX). Values in the range of
         0..249 are reserved; Values in the range of 250..32767 indicate
         algorithms not enrolled in standard list. It should be
         emphasized that algorithm IDs are independent for each
         algorithm type. But it is considered that pairs of types
         CRYPTO_TYPE_ENCRYPT and CRYPTO_TYPE_DECRYPT, CRYPTO_TYPE_SIGN
         and CRYPTO_TYPE_VERIFY, CRYPTO_TYPE_COMPRESS and
         CRYPTO_TYPE_UNCOMPRESS are equivalent because they define
         reverse actions of the same nature.









Smyslov                      Informational                      [Page 6]

RFC 2628                       Crypto API                      June 1999


      group - algorithm implementation group (variants algorithm
         implementations with various parameters not covered by
         CryptoAlgInfo structure). Values in the range of 0..32767 are
         well-known numbers defined in Appendix A; vendors may
         arbitrarily use values in the range of 32768..65535.

      type - algorithm type (CRYPTO_TYPE_XXX). Unambiguously determines
         algorithm application.

      version - version of algorithm implementation (CRYPTO_VER
         (maj,min)).

      flags - flags that characterize the algorithm and its
         implementation. All bits, that are not defined in Appendix A,
         must be zeroed.

      maxcontexts - maximum cryptographic contexts number that are
         simultaneously supported by the algorithm implementation (0 if
         the number is unlimited or is limited only by environmental
         conditions like memory size).

      name - text algorithm name (ASCII characters use only; all unused
         bytes must be set to 0).

   The next information depends on algorithm type:

   For encryption algorithms (CRYPTO_TYPE_ENCRYPT and
   CRYPTO_TYPE_DECRYPT):

      blocklen - data block length in bytes (value 1 must be used for
         stream cipher algorithms).

      keylen - encrypting (or decrypting) key length in bytes.

      outlen - output data size for conversion of one input data block
         in bytes. Usually it is equal to blocklen. When prediction of
         this value is impossible zero value must be indicated.

      milen - size of initialization vector (for block algorithms) or
         message indicator (for stream algorithms) in bytes. For block
         algorithms zero value of the parameter means that the algorithm
         implements ECB encoding. Non-zero milen parameter means that
         the algorithm implements CBC encoding. For stream algorithms
         zero value of the parameter means that the message indicator is
         not required.






Smyslov                      Informational                      [Page 7]

RFC 2628                       Crypto API                      June 1999


   For signature algorithms (CRYPTO_TYPE_SIGN):

      blocklen - block size in bytes. The length of input signature data
         will be padded up to this value. When there is no need in
         padding the value of 1 must be set.

      keylen - private key length in bytes.

      outlen - signature length in bytes. When prediction of this value
         is impossible 0 value must be indicated. If the signature
         consists of several values then the total length is indicated.

      milen - non-zero value specifies signature parameter length
         (random number), zero value indicates that the parameter is not
         required.

   For signature verification algorithms (CRYPTO_TYPE_VERIFY):

      blocklen - is not used.

      keylen - length of public key in bytes.

      outlen - signature length in bytes. When prediction of this value
         is impossible 0 value must be indicated. If the signature
         consists of several values then the total length is indicated.

      milen - is not used.

   For data compression algorithms (CRYPTO_TYPE_COMPRESS):

      blocklen - see outlen.

      keylen - is not used.

      outlen - if the algorithm provides the fixed compression with
         known value then it is indicated as blocklen/outlen ratio. The
         values can be arbitrary. If the compression value is not known
         then outlen is set to 0 and blocklen is not used.

      milen - is not used.

   For data uncompressing algorithms (CRYPTO_TYPE_UNCOMPRESS):

      blocklen - see outlen.

      keylen - is not used.





Smyslov                      Informational                      [Page 8]

RFC 2628                       Crypto API                      June 1999


      outlen - if the algorithm provides the fixed compression with
         known value then it is indicated as blocklen/outlen ratio. The
         values can be arbitrary. It is natural that the ratio will be
         reverse to the similar value for the same algorithm but of
         CRYPTO_TYPE_COMPRESS type. If the compression value is not
         known then outlen is set to 0 and blocklen is not used.

      milen - is not used.

   For one-way hash function algorithms (CRYPTO_TYPE_HASH):

      blocklen - block size in bytes. The length of input data will be
         padded up to this value. When there is no need in padding value
         1 should be used.

      keylen - is not used.

      outlen - resulting hash value length in bytes.

      milen - is not used.

   For random number generation algorithms (CRYPTO_TYPE_RANDOM):

      blocklen - is not used.

      keylen - initial seed length (0 - if not required, for example in
         a physical effects based generators).

      outlen - resulting random number length in bytes (0 - arbitrary)

      milen - is not used.

3.2. Cryptoplugin Deinitialization Function

   /* Plugin deinitialization */
   CRYPTO_STATUS   CryptoPluginFini(void);

   The function is called before the cryptoplugin operation is to be
   terminated. Function execution causes closing of all open
   cryptographic contexts, system resources deallocation and hardware
   deinitialization.  The value returned is informational only.

   Return codes for the function:

      CRYPTO_OK - cryptoplugin is deinitialized successfully.

      CRYPTO_ERR_GENERAL - internal error.




Smyslov                      Informational                      [Page 9]

RFC 2628                       Crypto API                      June 1999


      CRYPTO_ERR_UNCLOSED_HANDLES - warning that there were open
         cryptographic contexts during cryptoplugin deinitialization.
         The warning is informational only. The open contexts are
         destroyed anyway.

3.3. Cryptographic Context Opening Function

   New algorithm instance (cipher state) */
   CRYPTO_STATUS   CryptoOpen(

         CRYPTO_HANDLE   *state, /* Pointer to cipher state
                                    handle (filled on exit) */
         long            algnum, /* Algorithm number in
                                    CryptoPluginInfo structure */
         const char      *key);  /* key (in plain) */

   The function creates cryptographic context copy inside cryptoplugin
   and initializes it with the provided key. Later the handle of the
   context is used in calls of other algorithm functions.

   Description of parameters:

      state - pointer to the variable that will be set to the handle of
         the context created if succeeded. NULL parameter value should
         result in the CRYPTO_ERR_BAD_PARAMS code returned by the
         function.

      algnum - algorithm number in the cryptoplugin. It is equal to the
         number of CryptoAlgInfo structure (that describes the
         algorithm) in CryptoPluginInfo structure. The number begins
         with zero value. It should be taken into account that it is not
         an algorithm identifier but its number in the cryptoplugin.

      key - pointer to the key (if it is required) or to the seed (for
         random number generation algorithm).

Notes.

   1. Generated cryptographic context is stored inside the cryptoplugin
      until it will be destroyed by the CryptoAlgClose function call.
      The maximum number of cryptographic contexts supported by
      cryptoplugin can be indicated in algorithm parameters description.
      If maximum number of cryptographic contexts equals to zero then
      the cryptographic contexts number is either unlimited (for
      example, for stateless algorithms like random number generators
      and one-way hash functions) or it is limited by external factors
      only (like memory size).




Smyslov                      Informational                     [Page 10]

RFC 2628                       Crypto API                      June 1999


      Return codes for the function:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_NO_RESOURCES - insufficient internal resources.

      CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general
         CRYPTO_ERR_NO_RESOURCES error this code assumes that the
         calling module can release system memory (if it is in
         position to) and try to call the function once again.

      CRYPTO_ERR_BAD_PARAMS - invalid parameters (invalid algorithm
         number, zero pointer to the handle or to key (seed) if it is
      required.

3.4. Cryptographic Context Reopening Function

/* Reinitialize algorithm instance */
CRYPTO_STATUS   CryptoReOpen(
                CRYPTO_HANDLE   state, /* current cipher state handle */
                const char      *key);  /* key (in plain) */

   The function reinitializes an existing context. This function is used
   for key change without new system resources allocation. The function
   parameters are handle of opened earlier context and pointer to a new
   key.

   Return codes for the function:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle.

      CRYPTO_ERR_NO_RESOURCES - insufficient internal resources.

      CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general

      CRYPTO_ERR_NO_RESOURCES error this code assumes that the
         calling module may release system memory and try function
         call once more.

      CRYPTO_ERR_BAD_PARAMS - invalid parameters (invalid algorithm
         number, zero pointer to the handle or to key (seed) if it is
         required.



Smyslov                      Informational                     [Page 11]

RFC 2628                       Crypto API                      June 1999


3.5. Cryptographic Context Closing Function

/* Destroy algorithm instance */
CRYPTO_STATUS   CryptoClose(
                CRYPTO_HANDLE   state); /* Handle of cipher state */

   The function provides cryptographic context destruction. The
   cryptographic context handle is its parameter. The value returned is
   informational only.

   Return codes for the function:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle.

3.6. Key Verification Function

      /* Check key for possible weakness */
      CRYPTO_STATUS   CryptoCheckForWeakKey(
                    long            algnum, /* Algorithm number in
                                    CryptoPluginInfo structure */
                    const char      *key);  /* Proposed key */

   The function verifies key material whether it is weak (from the
   algorithm's point of view). The function is actual for
   encryption/decryption or signing/verification algorithms only.
   Algorithm number (similar to CryptoAlgOpen) and pointer to the key to
   be verified are the parameters.

   Return codes for the function:

      CRYPTO_O - the key has passed the test.

      CRYPTO_ERR_WEAK_KEY - the key has not passed the test (being weak
         or possibly weak).

      CRYPTO_ERR_NOT_SUPPORTED - is not supported.

      CRYPTO_ERR_NO_RESOURCES - insufficient internal resources.

      CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general
         CRYPTO_ERR_NO_RESOURCES error this code assumes that the
         calling module can release system memory (if it is in
         position to) and try to call the function once again.




Smyslov                      Informational                     [Page 12]

RFC 2628                       Crypto API                      June 1999


3.7. Data Transformation Function

/* Perform CryptoTransform (depends on cipher state type) */
CRYPTO_STATUS   CryptoTransform(
                CRYPTO_HANDLE   state,  /* Cipher state */
                const char      *inbuff,/* input data */
                long            inlen,  /* input data length */
                char            *outbuff,/* output buffer */
                long            *outlen,/* On entry - output buffer
                                          length, on exit -  number of
                                          bytes written to outbuff */
                char            *mi);   /* Message indicator  */

   This is a cryptographic data transformation function. Function call
   results and function parameters are dependent on algorithm type. For
   algorithm types CRYTO_TYPE_ENCRYPT, CRYPTO_TYPE_DECRYPT,
   CRYPTO_TYPE_SIGN and CRYPTO_TYPE_VERIFY (items 3.7.1 - 3.7.4)
   function call results are history independent.

   Note. Stream encryption algorithms may seem an "exception". However
   the same cryptoalgorithm handle must hide its history dependence. For
   algorithm types CRYPTO_TYPE_COMPRESS, CRYPTO_TYPE_UNCOMPRESS and
   CRYPTO_TYPE_HASH (items 3.7.5 - 3.7.7) function calls are history
   dependent. For the CRYPTO_TYPE_RANDOM algorithm function call may be
   for different implementations either dependent or independent on the
   history.

3.7.1. For CRYPTO_TYPE_ENCRYPT Algorithm Type:

      The function encrypts input data. Its parameters are intended for:

      inbuff - pointer to the input data. If this parameter is equal to
         NULL then the function should return the
         CRYPTO_ERR_BAD_PARAMS error code.

      inlen - input data size (in bytes). If the size indicated in
         algorithm description is divisible by blocklen then
         padding is not carried out. Otherwise the algorithm
         either caries out padding according to the algorithm
         standard or returns appropriate error code
         (CRYPTO_ERR_BAD_PARAMS). The zero parameter is allowed so
         that the function quits at once and returns CRYPTO_OK
         code.

      outbuff - output data buffer. NULL parameter value results in the
         outlen parameter setting to output buffer size required
         to encrypt the input buffer represented. In this case the
         CRYPTO_ERR_SMALL_BUFFER error should not be returned.



Smyslov                      Informational                     [Page 13]

RFC 2628                       Crypto API                      June 1999


      outlen - Output buffer size is an input function parameter while
         the number of bytes written in the output buffer is the
         output parameter. Both the NULL parameter value and the
         zero value addressed result in CRYPTO_ERR_BAD_PARAMS code
         returned by the function.

      mi - message indicator. Its content depends on whether the
         block or stream algorithm is applied. In the block
         algorithm case it is set to the last block encrypted.
         When the first block is encrypted mi parameter specifies
         initial initialization vector. In the stream algorithm
         case it is set to the offset of the first byte encrypted
         in the stream. If the algorithm uses the message
         indicator and the mi parameter value is set to NULL then
         function should return CRYPTO_ERR_BAD_PARAMS. If the
         algorithm (ECB Mode encrypting as an example) does not
         apply the message indicator then NULL value of mi is
         acceptable while non-NULL value should be ignored.

   Returned values:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle.

      CRYPTO_ERR_NO_RESOURCES - insufficient internal resources.

      CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general
         CRYPTO_ERR_NO_RESOURCES error this code assumes that the
         calling module can release system memory (if it is in
         position to) and try to call the function once again.

      CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size.

      CRYPTO_ERR_BAD_PARAMS - invalid parameters.

3.7.2. For CRYPTO_TYPE_DECRYPT Algorithm Type:

   The function decrypts the input data. Its parameters are intended for:

      inbuff - pointer to the input data. If the parameter is equal to
         NULL then the function should return the
         CRYPTO_ERR_BAD_PARAMS error code.

      inlen - input data size (in bytes). When the parameter is set to
         zero the function quits at once and CRYPTO_OK code is returned.



Smyslov                      Informational                     [Page 14]

RFC 2628                       Crypto API                      June 1999


      outbuff - output data buffer. NULL parameter value results in the
         outlen parameter setting to output buffer size required
         to decrypt the input buffer represented. In this case the
         CRYPTO_ERR_SMALL_BUFFER error should not be returned.

      outlen - Output buffer size is an input function parameter while
         the number of bytes written in the output buffer is the
         output parameter. Both the NULL parameter value and the
         zero value addressed result in CRYPTO_ERR_BAD_PARAMS code
         returned by the function.

      mi - message indicator. The content depends on whether the
         block or stream algorithm is applied. In the block
         algorithm case it is set to the last block encrypted.
         When the first block is decrypted mi specifies initial
         initialization vector. In the stream algorithm case it is
         set to the offset of the first byte decrypted in the
         stream. If the algorithm uses the message indicator and
         the mi parameter is set to NULL then function should
         return CRYPTO_ERR_BAD_PARAMS. If the algorithm (ECB Mode
         as an example) does not apply the message indicator then
         NULL value of mi is acceptable while non-NULL value
         should be ignored.

   Returned values:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle.

      CRYPTO_ERR_NO_RESOURCES - insufficient internal resources.

      CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general
         CRYPTO_ERR_NO_RESOURCES error this code assumes that the
         calling module can release system memory (if it is in
         position to) and try to call the function once again.

      CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size.

      CRYPTO_ERR_BAD_PARAMS - invalid parameters.

3.7.3. For CRYPTO_TYPE_SIGN Type Algorithm:

   The function signs the input data. Its parameters are intended for:





Smyslov                      Informational                     [Page 15]

RFC 2628                       Crypto API                      June 1999


   inbuff - pointer to the input data. If the parameter is equal to
      NULL then the function should return the
      CRYPTO_ERR_BAD_PARAMS code error.

   inlen - input data size (in bytes). If the size indicated in
      algorithm description is divisible by blocklen then
      padding is not carried out. Otherwise the algorithm
      either caries out padding according to the algorithm
      standard or returns appropriate error code
      (CRYPTO_ERR_BAD_PARAMS). The zero parameter is allowed so
      that the function quits at once and returns CRYPTO_OK
      code.

   outbuff - output data buffer. NULL parameter value results in the
      outlen parameter setting to output buffer size required
      to sign the input buffer represented. In this case the
      CRYPTO_ERR_SMALL_BUFFER error should not be returned.

   outlen - Output buffer size is an input function parameter while
      the number of bytes written in the output buffer is the
      output parameter. Both the NULL parameter value and the
      zero value addressed result in CRYPTO_ERR_BAD_PARAMS code
      returned by the function.

   mi - pointer to signature parameter (random number usually) if
      milen parameter in algorithm description is non-zero. In
      this case zero mi parameter indicates that the parameter
      should be chosen (generated) inside the algorithm. If
      milen parameter in algorithm description is set to zero
      then mi parameter is ignored.

   Returned values:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle.

      CRYPTO_ERR_NO_RESOURCES - insufficient internal resources.

      CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general
         CRYPTO_ERR_NO_RESOURCES error this code assumes that the
         calling module can release system memory (if it is in
         position to) and try to call the function once again.

      CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size.




Smyslov                      Informational                     [Page 16]

RFC 2628                       Crypto API                      June 1999


      CRYPTO_ERR_BAD_PARAMS - invalid parameters.

3.7.4. For CRYPTO_TYPE_VERIFY Algorithm Type:

   The function verifies input data signature. Its parameters are
   intended for:

      inbuff - pointer to the input data. If the parameter is equal to
         NULL then the function should return the CRYPTO_ERR_BAD_PARAMS
         code error.

      inlen - input data size (in bytes). The zero parameter is allowed
         so that the function quits at once and returns CRYPTO_OK code.

      outbuff -pointer to the signature. If the parameter is set to NULL
         then the function returns CRYPTO_ERR_BAD_PARAMS error code. If
         the signature consists of several parts then they are combined
         to one array.

      outlen - specifies the signature length if the signature length is
         set to zero in algorithm description structure. If non-zero
         value is specified in algorithm description structure then the
         parameter is ignored. If the signature consists of several
         parts then the maximum part length multiplied by the number of
         parts is specified.

      mi - is not used.

   Returned values:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_INVALID_SIGNATURE - invalid signature.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle.

      CRYPTO_ERR_NO_RESOURCES - insufficient internal resources.

      CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general
         CRYPTO_ERR_NO_RESOURCES error this code assumes that the
         calling module can release system memory (if it is in
         position to) and try to call the function once again.

      CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size.

      CRYPTO_ERR_BAD_PARAMS - invalid parameters.



Smyslov                      Informational                     [Page 17]

RFC 2628                       Crypto API                      June 1999


3.7.5. For CRYPTO_TYPE_COMPRESS Algorithm Type:

   The function compresses the input data. Its parameters are intended
   for:

      inbuff - pointer to the input data.

      inlen - input data size (in bytes). The zero parameter is allowed
         so that the function quits at once and returns CRYPTO_OK code.

      outbuff - output data buffer. NULL parameter value results in the
         outlen parameter setting to output buffer size required to
         compress the input buffer represented. In this case the
         CRYPTO_ERR_SMALL_BUFFER error should not be returned.

      outlen - Output buffer size is an input function parameter while
         the number of bytes written in the output buffer is the output
         parameter. Both the NULL parameter value and the zero value
         addressed result in CRYPTO_ERR_BAD_PARAMS code returned by the
         function.

      mi - is not used.

   Returned values:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle.

      CRYPTO_ERR_NO_RESOURCES - insufficient internal resources
         CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general
         CRYPTO_ERR_NO_RESOURCES error this code assumes that the
         calling module can release system memory (if it is in
         position to) and try to call the function once again.

      CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size.

      CRYPTO_ERR_BAD_PARAMS - invalid parameters.

3.7.6. For CRYPTO_TYPE_UNCOMPRESS Algorithm Type:

      The function decompresses the input data. Its parameters are
      intended for:

      inbuff - pointer to the input data.




Smyslov                      Informational                     [Page 18]

RFC 2628                       Crypto API                      June 1999


      inlen - input data size (in bytes). The zero parameter is allowed
         so that the function quits at once and returns CRYPTO_OK code.

      outbuff - output data buffer. NULL parameter value results in the
         outlen parameter setting to output buffer size required to
         decompress the input buffer represented. In this case the
         CRYPTO_ERR_SMALL_BUFFER error should not be returned.

      outlen - Output buffer size is an input function parameter while
         the number of bytes written in the output buffer is the output
         parameter. Both the NULL parameter value and the zero value
         addressed result in CRYPTO_ERR_BAD_PARAMS code returned by the
         function.

      mi - is not used.

   Returned values:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle.

      CRYPTO_ERR_NO_RESOURCES - insufficient internal resources.

      CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general
         CRYPTO_ERR_NO_RESOURCES error this code assumes that the
         calling module can release system memory (if it is in
         position to) and try to call the function once again.

      CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size.

      CRYPTO_ERR_BAD_PARAMS - invalid parameters.

3.7.7. For CRYPTO_TYPE_HASH Algorithm Type:

   The function calculates the hash value of the input data. Its
   parameters are intended for:

      inbuff - pointer to the input data. If the parameter is of NULL
         value then the function calculates cumulative hash value for
         the data represented (taking into account all previous data
         represented). If total length of all the data represented by
         the moment is divisible by blocklen and outbuff is non-NULL
         then it is returned to outbuff.  Nothing is written in outbuff
         when the length is not divisible by blocklen. NULL inbuff
         indicates the last conversion when the input data is padded up



Smyslov                      Informational                     [Page 19]

RFC 2628                       Crypto API                      June 1999


         to the blocklen size and the result is written to outbuff
         address. The padding procedure is defined for the algorithm.

      inlen - input data size (in bytes). The zero parameter is allowed
         when the function quits at once and returns CRYPTO_OK code.

      outbuff - output data buffer.

      outlen - Output buffer size is an input function parameter while
         the number of bytes written in the output buffer is the output
         parameter. If intermediate conversion value (inbuff is not
         NULL) and total length of data represented by the moment are
         not divisible by blocklen then outlen is set to zero and the
         hash value is not written in outbuff. Both the NULL parameter
         value and the zero value addressed result in
         CRYPTO_ERR_BAD_PARAMS code returned by the function.

      mi - is not used.

   Returned values:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle.

      CRYPTO_ERR_NO_RESOURCES - insufficient internal resources.

      CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general
         CRYPTO_ERR_NO_RESOURCES error this code assumes that the
         calling module can release system memory (if it is in position
         to) and try to call the function once again.

      CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size.

      CRYPTO_ERR_BAD_PARAMS - invalid parameters.














Smyslov                      Informational                     [Page 20]

RFC 2628                       Crypto API                      June 1999


3.7.8. For CRYPTO_TYPE_RANDOM Algorithm Type:

   The function generates a random number. Its parameters are intended
   for:

      inbuff - pointer to the input data used for generation (when one
         of the pseudorandom algorithms is implemented). NULL parameter
         indicates absence of the input data.

      inlen - input data size (in bytes).

      outbuff - output data

      outlen - Output buffer size is an input function parameter while
         the number of bytes written in the output buffer is the output
         parameter. If zero (i.e. arbitrary) generated number size is
         set in the algorithm description then the outlen value
         determines the number of random bytes required by the calling
         procedure.

      mi - is not used.

   Returned values:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle.

      CRYPTO_ERR_NO_RESOURCES - insufficient internal resources.

      CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general
         CRYPTO_ERR_NO_RESOURCES error this code assumes that the
         calling module can release system memory (if it is in
         position to) and try to call the function once again.

      CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size.

      CRYPTO_ERR_BAD_PARAMS - invalid parameters.











Smyslov                      Informational                     [Page 21]

RFC 2628                       Crypto API                      June 1999


3.8. Cryptographic Context Control Function

/* Algorithm control */
CRYPTO_STATUS   CryptoControl(
                CRYPTO_HANDLE   state,  /* Cipher state handle */
                long            cmd,    /* Control command */
                long            param,  /* Parameter id */
                char            val,    /* Parameter value */
                long            *len);  /* For CRYPTO_GET: on entry -
                                           val buffer length, on exit -
                                           number of bytes written to
                                           val; for CRYPTO_SET: length
                                           of value to set */

   The function provides cryptographic context internal parameters
   management. It may be used to check context parameters or to change
   the context state, for example it may return information about
   cryptoalgorithm (is given context uses hardware encryption
   facilities), or it may "scroll" stream algorithms context if
   necessary, etc.

   Description of parameters:

      state - cryptographic context handle.

      cmd - command (CRYPTO_GET or CRYPTO_SET).

   param - identifier of parameter. Values in the range of 0..32767
      are assigned well-known numbers for all algorithms.
      Values in the range of 32768..65535 mean various
      variables for various algorithms (may be arbitrarily used
      by cryptolibrary developer).

   val - pointer to the data buffer.

   len - data size (in bytes).

   Returned values:

      CRYPTO_OK - successful completion.

      CRYPTO_ERR_GENERAL - internal error.

      CRYPTO_ERR_BAD_HANDLE - invalid cryptographic context handle.

      CRYPTO_ERR_NO_RESOURCES - insufficient internal resources.

      CRYPTO_ERR_NO_MEMORY - not enough memory. Contrary to general



Smyslov                      Informational                     [Page 22]

RFC 2628                       Crypto API                      June 1999


         CRYPTO_ERR_NO_RESOURCES error this code assumes that the
         calling module can release system memory (if it is in
         position to) and try to call the function once again.

      CRYPTO_ERR_SMALL_BUFFER - insufficient output buffer size.

      CRYPTO_ERR_BAD_PARAMS - invalid parameters.

4. Cryptoplugin Registration Procedure

   Cryptoplugin should be linked together with the cryptoplugin wrapper
   library delivered by the cryptoplugin's client developer according to
   the rules specified by the module-client developer for each platform.
   It should result in a driver (module) of appropriate operating system
   that implements the cryptolibrary functions. The driver should be one
   of the drivers loaded during operating system boot. The procedure of
   cryptoplugin driver installation should be defined, documented, and
   automated when necessary, by the cryptoplugin developer. At the
   beginning of operation the driver-client determines cryptoplugin
   driver availability and establishes interconnection with it. Both
   module-client configuration and current security policy determine
   data conversion algorithms to be chosen.

5. Security Considerations

   Security issues are addressed throughout this memo.

6. References

   [Schneier] Bruce Schneier, Applied Cryptography - Protocols,
              Algorithms, and Source Code in C (Second Edition), John
              Wiley & Sons, Inc., 1996.

   [IPsec]    Kent, S. and R. Atkinson, "Security Architecture for the
              Internet Protocol", RFC 2401, November 1998.

   [ISAKMP]   Maughhan, D., Schertler, M. Schneider, M. and J. Turner,
              "Internet Security Association and Key Management Protocol
              (ISAKMP)", RFC 2408, November 1998.

   [IKE]      Harkins, D. and D. Carrel, "The Internet Key Exchange
              (IKE)", RFC 2409, November 1998.

   [TLS]      Dierks, T. and C. Allen, "The TLS protocol Version 1.0",
              RFC 2246, January 1999.






Smyslov                      Informational                     [Page 23]

RFC 2628                       Crypto API                      June 1999


7. Author's Address

   Valery Smyslov
   TWS
   Centralny prospekt, 11,
   Moscow, Russia

   Phone: +7 (095) 531 4633
   Fax:   +7 (095) 531 2403
   EMail: svan@trustworks.com









































Smyslov                      Informational                     [Page 24]

RFC 2628                       Crypto API                      June 1999


Appendix A. The interface specification as a C header file

#ifndef __CRYPTPI_H
#define __CRYPTPI_H

#define CRYPTO_VER(maj,min)     (((maj & 0xff) << 8) | (min & 0xff))
#define CRYPTO_MAJ_VER(ver)     ((ver >> 8) & 0xff)
#define CRYPTO_MIN_VER(ver)     (ver & 0xff)

#define CRYPTO_PLUGIN_NAME_LEN  64      /* Must be multiple of 4 to */
#define CRYPTO_ALG_NAME_LEN     32      /* avoid alignment problems */

#ifndef CRYPTO_HANDLE
#define CRYPTO_HANDLE           void*   /* cipher state handle */
#endif

typedef enum tag_CRYPTO_STATUS {
        CRYPTO_OK = 1,                  /* success */
        CRYPTO_ERR_GENERAL,             /* undefined (internal) error */
        CRYPTO_ERR_NOT_SUPPORTED,       /* unsupported */
        CRYPTO_ERR_BAD_HANDLE,          /* invalid handle */
        CRYPTO_ERR_SMALL_BUFFER,        /* insufficient output buffer
                                           size */
        CRYPTO_ERR_WEAK_KEY,            /* key is considered to be weak
                                           (semiweak, pseudoweak) */
        CRYPTO_ERR_NO_RESOURCES,        /* insufficient resources to
                                           perform operation */
        CRYPTO_ERR_NO_MEMORY,           /* insufficient memory to
                                           perform operation */
        CRYPTO_ERR_BAD_PARAMS,          /* invalid parameters */
        CRYPTO_ERR_HARDWARE,            /* hardware error */
        CRYPTO_ERR_INVALID_SIGNATURE,   /* invalid signature */
        CRYPTO_ERR_UNCLOSED_HANDLES     /* unclosed handles exist while
                                           plugin deinitializises */
} CRYPTO_STATUS;

/* CryptoControl commands */
#define CRYPTO_GET                      1       /* get parameter */
#define CRYPTO_SET                      2       /* set parameter */

/* Currently defined algorithm types */
#define CRYPTO_TYPE_ENCRYPT             1
#define CRYPTO_TYPE_DECRYPT             2
#define CRYPTO_TYPE_SIGN                3
#define CRYPTO_TYPE_VERIFY              4
#define CRYPTO_TYPE_COMPRESS            5
#define CRYPTO_TYPE_UNCOMPRESS          6
#define CRYPTO_TYPE_HASH                7



Smyslov                      Informational                     [Page 25]

RFC 2628                       Crypto API                      June 1999


#define CRYPTO_TYPE_RANDOM              8

/* Currently defined algorithm IDs (for types
   CRYPTO_TYPE_ENCRYPT & CRYPTO_TYPE_DECRYPT) */
#define CRYPTO_AE_DUMMY                 1       /* no encryption */
#define CRYPTO_AE_DES                   2       /* DES-CBC */
#define CRYPTO_AE_3DES_EDE              3       /* Triple DES-EDE-CBC */
#define CRYPTO_AE_IDEA                  4       /* IDEA-CBC */
#define CRYPTO_AE_RC2                   5       /* RC2 */
#define CRYPTO_AE_RC4                   6       /* RC4 */
#define CRYPTO_AE_RC5                   7       /* RC5 */
#define CRYPTO_AE_SAFER                 8       /* SAFER */
#define CRYPTO_AE_CAST                  9       /* CAST */
#define CRYPTO_AE_BLOWFISH              10      /* Blowfish */
#define CRYPTO_AE_RSA                   11      /* RSA */
#define CRYPTO_AE_GOST                  12      /* GOST */

/* Currently defined algorithm IDs (for types
   CRYPTO_TYPE_SIGN & CRYPTO_TYPE_VERIFY) */
#define CRYPTO_AS_RSA                   2       /* RSA */
#define CRYPTO_AS_DSA                   3       /* DSA */
#define CRYPTO_AS_GOST                  4       /* GOST */

/* Currently defined algorithm IDs (for types
   CRYPTO_TYPE_COMPRESS & CRYPTO_TYPE_UNCOMPRESS) */
#define CRYPTO_AC_DUMMY                 1       /* no compression */
#define CRYPTO_AC_DEFLATE               2       /* Deflate */
#define CRYPTO_AC_LZS                   3       /* LZS */

/* Currently defined algorithm IDs (for type CRYPTO_TYPE_HASH) */
#define CRYPTO_AH_MD5                   1       /* MD5 */
#define CRYPTO_AH_SHA                   2       /* SHA-1 */
#define CRYPTO_AH_GOST                  3       /* GOST */

/* Currently defined algorithm IDs (for type CRYPTO_TYPE_RANDOM) */
#define         CRYPTO_AR_UNKNOWN       1

/* Currently defined plugin flags */
#define CRYPTO_PLUGIN_HARDWARE          1       /* plugin uses hdw */
/* TBD more */

/* Currently defined algorithm flags */
#define CRYPTO_ALG_HARDWARE             1       /* algorithm implemented
                                                   in hardware */
#define CRYPTO_ALG_MULTITHREADED        2       /* implementation allows
                                                   multithreading */
/* TBD more */




Smyslov                      Informational                     [Page 26]

RFC 2628                       Crypto API                      June 1999


/* Currently defined parameters identifiers for CryptoControl */
#define CRYPTO_PARAM_KEY                1       /* Only for CRYPTO_GET -
                                                   get current key */
/* TBD more */

typedef struct  tag_CryptoAlgInfo {
        long    status;                 /* Algorithm status */
        long    type;                   /* algorithm type (One of
                                           CRYPTO_TYPE_XXX) */
        long    id;                     /* algorithm ID */
        long    group;                  /* algorithm group */
        long    version;                /* algorithm version
                                           (CRYPTO_VER) */
        long    flags;                  /* algorithm flags
                                           (CRYPTO_ALG_XXX) */
        long    maxcontexts;            /* max number of cipher states
                                           supported (0 - any) */
        char    name[CRYPTO_ALG_NAME_LEN];      /* algorithm name */
                          /* CRYPT   SIGN    COMPRESS HASH    RANDOM  */
                          /* DECRYPT VERIFY                           */
        long    blocklen; /* blklen (blklen)  inlen   blklen    -     */
        long    keylen;   /* keylen  keylen     -       -     seedlen */
        long    outlen;   /* outlen (signlen) outlen  hashlen randlen */
        long    milen;    /* milen   (param)    -       -       -     */
} CryptoAlgInfo;

typedef struct  tag_CryptoPluginInfo {
        long    cpi_version;            /* Crypto PI version (currently
                                           CRYPTO_VER(1,0)) */
        long    status;                 /* Plugin status */
        char    name[CRYPTO_PLUGIN_NAME_LEN];   /* plugin text
                                                   description */
        long    version;                /* plugin version
                                           (CRYPTO_VER) */
        long    flags;                  /* plugin flags
                                           (CRYPTO_PLUGIN_XXX) */
        long    number_of_algs;         /* number of AlgInfo structures
                                           followed (min 1) */
        CryptoAlgInfo   algs[1];        /* array of AlgInfo structures
                                           (min 1) */
} CryptoPluginInfo;

#ifdef __cplusplus
extern "C" {
#endif

/* CryptoPlugin initialization. Returns pointer to CryptoPluginInfo
structure on success or NULL on fatal error. */



Smyslov                      Informational                     [Page 27]

RFC 2628                       Crypto API                      June 1999


CryptoPluginInfo *CryptoPluginInit(
                void            *param);/* Ptr to OS parameters
                                           (platform-specific) */

/* Plugin deinitialization */
CRYPTO_STATUS   CryptoPluginFini(void);

/* Get new algorithm instance (cipher state) */
CRYPTO_STATUS   CryptoOpen(
                CRYPTO_HANDLE   *state, /* Pointer to cipher state
                                            handle (filled on exit) */
                 long            algnum, /* Algorithm number in
                                            CryptoPluginInfo structure */
                 const char      *key);  /* key (in plain) */

 /* Reinitialize algorithm instance */
 CRYPTO_STATUS   CryptoReOpen(
                 CRYPTO_HANDLE   state, /* current cipher state handle */
                 const char      *key);  /* key (in plain) */

 /* Destroy algorithm instance */
 CRYPTO_STATUS   CryptoClose(
                 CRYPTO_HANDLE   state); /* Handle of cipher state */

 /* Check key for possible weakness */
 CRYPTO_STATUS   CryptoCheckForWeakKey(
                 long            algnum, /* Algorithm number in
                                            CryptoPluginInfo structure */
                 const char      *key);  /* Proposed key */

 /* Perform CryptoTransform (depends on cipher state type) */
 CRYPTO_STATUS   CryptoTransform(
                 CRYPTO_HANDLE   state,  /* Cipher state handle */
                 const char      *inbuff,/* input data */
                 long            inlen,  /* input data length */
                 char            *outbuff,/* output buffer */
                 long            *outlen,/* On entry - output buffer
                                           length, on exit -  number of
                                           bytes written to outbuff */
                 char            *mi);   /* Message indicator  */

 /* Algorithm control */
 CRYPTO_STATUS   CryptoControl(
                 CRYPTO_HANDLE   state,  /* Cipher state handle */
                 long            cmd,    /* Control command */
                 long            param,  /* Parameter id */
                 char            val,    /* Parameter value */
                 long            *len);  /* For CRYPTO_GET: on entry -



Smyslov                      Informational                     [Page 28]

RFC 2628                       Crypto API                      June 1999


                                            val buffer length, on exit -
                                            number of bytes written to
                                            val; for CRYPTO_SET: length
                                            of value to set */

 #ifdef __cplusplus
 }
 #endif

 #endif  /* __CRYPTPI_H */









































Smyslov                      Informational                     [Page 29]

RFC 2628                       Crypto API                      June 1999


Full Copyright Statement

   Copyright (C) The Internet Society (1999).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.



















Smyslov                      Informational                     [Page 30]