Newer
Older
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
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
This documentation is rather sparse, you are probably best
off looking at the code for specific details.
The BIO library is a IO abstraction that was originally
inspired by the need to have callbacks to perform IO to FILE
pointers when using Windows 3.1 DLLs. There are two types
of BIO; a source/sink type and a filter type.
The source/sink methods are as follows:
- BIO_s_mem() memory buffer - a read/write byte array that
grows until memory runs out :-).
- BIO_s_file() FILE pointer - A wrapper around the normal
'FILE *' commands, good for use with stdin/stdout.
- BIO_s_fd() File descriptor - A wrapper around file
descriptors, often used with pipes.
- BIO_s_socket() Socket - Used around sockets. It is
mostly in the Microsoft world that sockets are different
from file descriptors and there are all those ugly winsock
commands.
- BIO_s_null() Null - read nothing and write nothing.; a
useful endpoint for filter type BIO's specifically things
like the message digest BIO.
The filter types are
- BIO_f_buffer() IO buffering - does output buffering into
larger chunks and performs input buffering to allow gets()
type functions.
- BIO_f_md() Message digest - a transparent filter that can
be asked to return a message digest for the data that has
passed through it.
- BIO_f_cipher() Encrypt or decrypt all data passing
through the filter.
- BIO_f_base64() Base64 decode on read and encode on write.
- BIO_f_ssl() A filter that performs SSL encryption on the
data sent through it.
Base BIO functions.
The BIO library has a set of base functions that are
implemented for each particular type. Filter BIOs will
normally call the equivalent function on the source/sink BIO
that they are layered on top of after they have performed
some modification to the data stream. Multiple filter BIOs
can be 'push' into a stack of modifers, so to read from a
file, unbase64 it, then decrypt it, a BIO_f_cipher,
BIO_f_base64 and a BIO_s_file would probably be used. If a
sha-1 and md5 message digest needed to be generated, a stack
two BIO_f_md() BIOs and a BIO_s_null() BIO could be used.
The base functions are
- BIO *BIO_new(BIO_METHOD *type); Create a new BIO of type 'type'.
- int BIO_free(BIO *a); Free a BIO structure. Depending on
the configuration, this will free the underlying data
object for a source/sink BIO.
- int BIO_read(BIO *b, char *data, int len); Read upto 'len'
bytes into 'data'.
- int BIO_gets(BIO *bp,char *buf, int size); Depending on
the BIO, this can either be a 'get special' or a get one
line of data, as per fgets();
- int BIO_write(BIO *b, char *data, int len); Write 'len'
bytes from 'data' to the 'b' BIO.
- int BIO_puts(BIO *bp,char *buf); Either a 'put special' or
a write null terminated string as per fputs().
- long BIO_ctrl(BIO *bp,int cmd,long larg,char *parg); A
control function which is used to manipulate the BIO
structure and modify it's state and or report on it. This
function is just about never used directly, rather it
should be used in conjunction with BIO_METHOD specific
macros.
- BIO *BIO_push(BIO *new_top, BIO *old); new_top is apped to the
top of the 'old' BIO list. new_top should be a filter BIO.
All writes will go through 'new_top' first and last on read.
'old' is returned.
- BIO *BIO_pop(BIO *bio); the new topmost BIO is returned, NULL if
there are no more.
If a particular low level BIO method is not supported
(normally BIO_gets()), -2 will be returned if that method is
called. Otherwise the IO methods (read, write, gets, puts)
will return the number of bytes read or written, and 0 or -1
for error (or end of input). For the -1 case,
BIO_should_retry(bio) can be called to determine if it was a
genuine error or a temporary problem. -2 will also be
returned if the BIO has not been initalised yet, in all
cases, the correct error codes are set (accessible via the
ERR library).
The following functions are convenience functions:
- int BIO_printf(BIO *bio, char * format, ..); printf but
to a BIO handle.
- long BIO_ctrl_int(BIO *bp,int cmd,long larg,int iarg); a
convenience function to allow a different argument types
to be passed to BIO_ctrl().
- int BIO_dump(BIO *b,char *bytes,int len); output 'len'
bytes from 'bytes' in a hex dump debug format.
- long BIO_debug_callback(BIO *bio, int cmd, char *argp, int
argi, long argl, long ret) - a default debug BIO callback,
this is mentioned below. To use this one normally has to
use the BIO_set_callback_arg() function to assign an
output BIO for the callback to use.
- BIO *BIO_find_type(BIO *bio,int type); when there is a 'stack'
of BIOs, this function scan the list and returns the first
that is of type 'type', as listed in buffer.h under BIO_TYPE_XXX.
- void BIO_free_all(BIO *bio); Free the bio and all other BIOs
in the list. It walks the bio->next_bio list.
Extra commands are normally implemented as macros calling BIO_ctrl().
- BIO_number_read(BIO *bio) - the number of bytes processed
by BIO_read(bio,.).
- BIO_number_written(BIO *bio) - the number of bytes written
by BIO_write(bio,.).
- BIO_reset(BIO *bio) - 'reset' the BIO.
- BIO_eof(BIO *bio) - non zero if we are at the current end
of input.
- BIO_set_close(BIO *bio, int close_flag) - set the close flag.
- BIO_get_close(BIO *bio) - return the close flag.
BIO_pending(BIO *bio) - return the number of bytes waiting
to be read (normally buffered internally).
- BIO_flush(BIO *bio) - output any data waiting to be output.
- BIO_should_retry(BIO *io) - after a BIO_read/BIO_write
operation returns 0 or -1, a call to this function will
return non zero if you should retry the call later (this
is for non-blocking IO).
- BIO_should_read(BIO *io) - we should retry when data can
be read.
- BIO_should_write(BIO *io) - we should retry when data can
be written.
- BIO_method_name(BIO *io) - return a string for the method name.
- BIO_method_type(BIO *io) - return the unique ID of the BIO method.
- BIO_set_callback(BIO *io, long (*callback)(BIO *io, int
cmd, char *argp, int argi, long argl, long ret); - sets
the debug callback.
- BIO_get_callback(BIO *io) - return the assigned function
as mentioned above.
- BIO_set_callback_arg(BIO *io, char *arg) - assign some
data against the BIO. This is normally used by the debug
callback but could in reality be used for anything. To
get an idea of how all this works, have a look at the code
in the default debug callback mentioned above. The
callback can modify the return values.
Details of the BIO_METHOD structure.
typedef struct bio_method_st
{
int type;
char *name;
int (*bwrite)();
int (*bread)();
int (*bputs)();
int (*bgets)();
long (*ctrl)();
int (*create)();
int (*destroy)();
} BIO_METHOD;
The 'type' is the numeric type of the BIO, these are listed in buffer.h;
'Name' is a textual representation of the BIO 'type'.
The 7 function pointers point to the respective function
methods, some of which can be NULL if not implemented.
The BIO structure
typedef struct bio_st
{
BIO_METHOD *method;
long (*callback)(BIO * bio, int mode, char *argp, int
argi, long argl, long ret);
char *cb_arg; /* first argument for the callback */
int init;
int shutdown;
int flags; /* extra storage */
int num;
char *ptr;
struct bio_st *next_bio; /* used by filter BIOs */
int references;
unsigned long num_read;
unsigned long num_write;
} BIO;
- 'Method' is the BIO method.
- 'callback', when configured, is called before and after
each BIO method is called for that particular BIO. This
is intended primarily for debugging and of informational feedback.
- 'init' is 0 when the BIO can be used for operation.
Often, after a BIO is created, a number of operations may
need to be performed before it is available for use. An
example is for BIO_s_sock(). A socket needs to be
assigned to the BIO before it can be used.
- 'shutdown', this flag indicates if the underlying
communication primitive being used should be closed/freed
when the BIO is closed.
- 'flags' is used to hold extra state. It is primarily used
to hold information about why a non-blocking operation
failed and to record startup protocol information for the
SSL BIO.
- 'num' and 'ptr' are used to hold instance specific state
like file descriptors or local data structures.
- 'next_bio' is used by filter BIOs to hold the pointer of the
next BIO in the chain. written data is sent to this BIO and
data read is taken from it.
- 'references' is used to indicate the number of pointers to
this structure. This needs to be '1' before a call to
BIO_free() is made if the BIO_free() function is to
actually free() the structure, otherwise the reference
count is just decreased. The actual BIO subsystem does
not really use this functionality but it is useful when
used in more advanced applicaion.
- num_read and num_write are the total number of bytes
read/written via the 'read()' and 'write()' methods.
BIO_ctrl operations.
The following is the list of standard commands passed as the
second parameter to BIO_ctrl() and should be supported by
all BIO as best as possible. Some are optional, some are
manditory, in any case, where is makes sense, a filter BIO
should pass such requests to underlying BIO's.
- BIO_CTRL_RESET - Reset the BIO back to an initial state.
- BIO_CTRL_EOF - return 0 if we are not at the end of input,
non 0 if we are.
- BIO_CTRL_INFO - BIO specific special command, normal
information return.
- BIO_CTRL_SET - set IO specific parameter.
- BIO_CTRL_GET - get IO specific parameter.
- BIO_CTRL_GET_CLOSE - Get the close on BIO_free() flag, one
of BIO_CLOSE or BIO_NOCLOSE.
- BIO_CTRL_SET_CLOSE - Set the close on BIO_free() flag.
- BIO_CTRL_PENDING - Return the number of bytes available
for instant reading
- BIO_CTRL_FLUSH - Output pending data, return number of bytes output.
- BIO_CTRL_SHOULD_RETRY - After an IO error (-1 returned)
should we 'retry' when IO is possible on the underlying IO object.
- BIO_CTRL_RETRY_TYPE - What kind of IO are we waiting on.
The following command is a special BIO_s_file() specific option.
- BIO_CTRL_SET_FILENAME - specify a file to open for IO.
The BIO_CTRL_RETRY_TYPE needs a little more explanation.
When performing non-blocking IO, or say reading on a memory
BIO, when no data is present (or cannot be written),
BIO_read() and/or BIO_write() will return -1.
BIO_should_retry(bio) will return true if this is due to an
IO condition rather than an actual error. In the case of
BIO_s_mem(), a read when there is no data will return -1 and
a should retry when there is more 'read' data.
The retry type is deduced from 2 macros
BIO_should_read(bio) and BIO_should_write(bio).
Now while it may appear obvious that a BIO_read() failure
should indicate that a retry should be performed when more
read data is available, this is often not true when using
things like an SSL BIO. During the SSL protocol startup
multiple reads and writes are performed, triggered by any
SSL_read or SSL_write.
So to write code that will transparently handle either a
socket or SSL BIO,
i=BIO_read(bio,..)
if (I == -1)
{
if (BIO_should_retry(bio))
{
if (BIO_should_read(bio))
{
/* call us again when BIO can be read */
}
if (BIO_should_write(bio))
{
/* call us again when BIO can be written */
}
}
}
At this point in time only read and write conditions can be
used but in the future I can see the situation for other
conditions, specifically with SSL there could be a condition
of a X509 certificate lookup taking place and so the non-
blocking BIO_read would require a retry when the certificate
lookup subsystem has finished it's lookup. This is all
makes more sense and is easy to use in a event loop type
setup.
When using the SSL BIO, either SSL_read() or SSL_write()s
can be called during the protocol startup and things will
still work correctly.
The nice aspect of the use of the BIO_should_retry() macro
is that all the errno codes that indicate a non-fatal error
are encapsulated in one place. The Windows specific error
codes and WSAGetLastError() calls are also hidden from the
application.
Notes on each BIO method.
Normally buffer.h is just required but depending on the
BIO_METHOD, ssl.h or evp.h will also be required.
BIO_METHOD *BIO_s_mem(void);
- BIO_set_mem_buf(BIO *bio, BUF_MEM *bm, int close_flag) -
set the underlying BUF_MEM structure for the BIO to use.
- BIO_get_mem_ptr(BIO *bio, char **pp) - if pp is not NULL,
set it to point to the memory array and return the number
of bytes available.
A read/write BIO. Any data written is appended to the
memory array and any read is read from the front. This BIO
can be used for read/write at the same time. BIO_gets() is
supported in the fgets() sense.
BIO_CTRL_INFO can be used to retrieve pointers to the memory
buffer and it's length.
BIO_METHOD *BIO_s_file(void);
- BIO_set_fp(BIO *bio, FILE *fp, int close_flag) - set 'FILE *' to use.
- BIO_get_fp(BIO *bio, FILE **fp) - get the 'FILE *' in use.
- BIO_read_filename(BIO *bio, char *name) - read from file.
- BIO_write_filename(BIO *bio, char *name) - write to file.
- BIO_append_filename(BIO *bio, char *name) - append to file.
This BIO sits over the normal system fread()/fgets() type
functions. Gets() is supported. This BIO in theory could be
used for read and write but it is best to think of each BIO
of this type as either a read or a write BIO, not both.
BIO_METHOD *BIO_s_socket(void);
BIO_METHOD *BIO_s_fd(void);
- BIO_sock_should_retry(int i) - the underlying function
used to determine if a call should be retried; the
argument is the '0' or '-1' returned by the previous BIO
operation.
- BIO_fd_should_retry(int i) - same as the
- BIO_sock_should_retry() except that it is different internally.
- BIO_set_fd(BIO *bio, int fd, int close_flag) - set the
file descriptor to use
- BIO_get_fd(BIO *bio, int *fd) - get the file descriptor.
These two methods are very similar. Gets() is not
supported, if you want this functionality, put a
BIO_f_buffer() onto it. This BIO is bi-directional if the
underlying file descriptor is. This is normally the case
for sockets but not the case for stdio descriptors.
BIO_METHOD *BIO_s_null(void);
Read and write as much data as you like, it all disappears
into this BIO.
BIO_METHOD *BIO_f_buffer(void);
- BIO_get_buffer_num_lines(BIO *bio) - return the number of
complete lines in the buffer.
- BIO_set_buffer_size(BIO *bio, long size) - set the size of
the buffers.
This type performs input and output buffering. It performs
both at the same time. The size of the buffer can be set
via the set buffer size option. Data buffered for output is
only written when the buffer fills.
BIO_METHOD *BIO_f_ssl(void);
- BIO_set_ssl(BIO *bio, SSL *ssl, int close_flag) - the SSL
structure to use.
- BIO_get_ssl(BIO *bio, SSL **ssl) - get the SSL structure
in use.
The SSL bio is a little different from normal BIOs because
the underlying SSL structure is a little different. A SSL
structure performs IO via a read and write BIO. These can
be different and are normally set via the
SSL_set_rbio()/SSL_set_wbio() calls. The SSL_set_fd() calls
are just wrappers that create socket BIOs and then call
SSL_set_bio() where the read and write BIOs are the same.
The BIO_push() operation makes the SSLs IO BIOs the same, so
make sure the BIO pushed is capable of two directional
traffic. If it is not, you will have to install the BIOs
via the more conventional SSL_set_bio() call. BIO_pop() will retrieve
the 'SSL read' BIO.
BIO_METHOD *BIO_f_md(void);
- BIO_set_md(BIO *bio, EVP_MD *md) - set the message digest
to use.
- BIO_get_md(BIO *bio, EVP_MD **mdp) - return the digest
method in use in mdp, return 0 if not set yet.
- BIO_reset() reinitializes the digest (EVP_DigestInit())
and passes the reset to the underlying BIOs.
All data read or written via BIO_read() or BIO_write() to
this BIO will be added to the calculated digest. This
implies that this BIO is only one directional. If read and
write operations are performed, two separate BIO_f_md() BIOs
are reuqired to generate digests on both the input and the
output. BIO_gets(BIO *bio, char *md, int size) will place the
generated digest into 'md' and return the number of bytes.
The EVP_MAX_MD_SIZE should probably be used to size the 'md'
array. Reading the digest will also reset it.
BIO_METHOD *BIO_f_cipher(void);
- BIO_reset() reinitializes the cipher.
- BIO_flush() should be called when the last bytes have been
output to flush the final block of block ciphers.
- BIO_get_cipher_status(BIO *b), when called after the last
read from a cipher BIO, returns non-zero if the data
decrypted correctly, otherwise, 0.
- BIO_set_cipher(BIO *b, EVP_CIPHER *c, unsigned char *key,
unsigned char *iv, int encrypt) This function is used to
setup a cipher BIO. The length of key and iv are
specified by the choice of EVP_CIPHER. Encrypt is 1 to
encrypt and 0 to decrypt.
BIO_METHOD *BIO_f_base64(void);
- BIO_flush() should be called when the last bytes have been output.
This BIO base64 encodes when writing and base64 decodes when
reading. It will scan the input until a suitable begin line
is found. After reading data, BIO_reset() will reset the
BIO to start scanning again. Do not mix reading and writing
on the same base64 BIO. It is meant as a single stream BIO.
Directions type
both BIO_s_mem()
one/both BIO_s_file()
both BIO_s_fd()
both BIO_s_socket()
both BIO_s_null()
both BIO_f_buffer()
one BIO_f_md()
one BIO_f_cipher()
one BIO_f_base64()
both BIO_f_ssl()
It is easy to mix one and two directional BIOs, all one has
to do is to keep two separate BIO pointers for reading and
writing and be careful about usage of underlying BIOs. The
SSL bio by it's very nature has to be two directional but
the BIO_push() command will push the one BIO into the SSL
BIO for both reading and writing.
The best example program to look at is apps/enc.c and/or perhaps apps/dgst.c.
==== blowfish.doc ========================================================
The Blowfish library.
Blowfish is a block cipher that operates on 64bit (8 byte) quantities. It
uses variable size key, but 128bit (16 byte) key would normally be considered
good. It can be used in all the modes that DES can be used. This
library implements the ecb, cbc, cfb64, ofb64 modes.
Blowfish is quite a bit faster that DES, and much faster than IDEA or
RC2. It is one of the faster block ciphers.
For all calls that have an 'input' and 'output' variables, they can be the
same.
This library requires the inclusion of 'blowfish.h'.
All of the encryption functions take what is called an BF_KEY as an
argument. An BF_KEY is an expanded form of the Blowfish key.
For all modes of the Blowfish algorithm, the BF_KEY used for
decryption is the same one that was used for encryption.
The define BF_ENCRYPT is passed to specify encryption for the functions
that require an encryption/decryption flag. BF_DECRYPT is passed to
specify decryption.
Please note that any of the encryption modes specified in my DES library
could be used with Blowfish. I have only implemented ecb, cbc, cfb64 and
ofb64 for the following reasons.
- ecb is the basic Blowfish encryption.
- cbc is the normal 'chaining' form for block ciphers.
- cfb64 can be used to encrypt single characters, therefore input and output
do not need to be a multiple of 8.
- ofb64 is similar to cfb64 but is more like a stream cipher, not as
secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
- If you want triple Blowfish, thats 384 bits of key and you must be totally
obsessed with security. Still, if you want it, it is simple enough to
copy the function from the DES library and change the des_encrypt to
BF_encrypt; an exercise left for the paranoid reader :-).
The functions are as follows:
void BF_set_key(
BF_KEY *ks;
int len;
unsigned char *key;
BF_set_key converts an 'len' byte key into a BF_KEY.
A 'ks' is an expanded form of the 'key' which is used to
perform actual encryption. It can be regenerated from the Blowfish key
so it only needs to be kept when encryption or decryption is about
to occur. Don't save or pass around BF_KEY's since they
are CPU architecture dependent, 'key's are not. Blowfish is an
interesting cipher in that it can be used with a variable length
key. 'len' is the length of 'key' to be used as the key.
A 'len' of 16 is recomended by me, but blowfish can use upto
72 bytes. As a warning, blowfish has a very very slow set_key
function, it actually runs BF_encrypt 521 times.
void BF_encrypt(unsigned long *data, BF_KEY *key);
void BF_decrypt(unsigned long *data, BF_KEY *key);
These are the Blowfish encryption function that gets called by just
about every other Blowfish routine in the library. You should not
use this function except to implement 'modes' of Blowfish.
I say this because the
functions that call this routine do the conversion from 'char *' to
long, and this needs to be done to make sure 'non-aligned' memory
access do not occur.
Data is a pointer to 2 unsigned long's and key is the
BF_KEY to use.
void BF_ecb_encrypt(
unsigned char *in,
unsigned char *out,
BF_KEY *key,
int encrypt);
This is the basic Electronic Code Book form of Blowfish (in DES this
mode is called Electronic Code Book so I'm going to use the term
for blowfish as well.
Input is encrypted into output using the key represented by
key. Depending on the encrypt, encryption or
decryption occurs. Input is 8 bytes long and output is 8 bytes.
void BF_cbc_encrypt(
unsigned char *in,
unsigned char *out,
long length,
BF_KEY *ks,
unsigned char *ivec,
int encrypt);
This routine implements Blowfish in Cipher Block Chaining mode.
Input, which should be a multiple of 8 bytes is encrypted
(or decrypted) to output which will also be a multiple of 8 bytes.
The number of bytes is in length (and from what I've said above,
should be a multiple of 8). If length is not a multiple of 8, bad
things will probably happen. ivec is the initialisation vector.
This function updates iv after each call so that it can be passed to
the next call to BF_cbc_encrypt().
void BF_cfb64_encrypt(
unsigned char *in,
unsigned char *out,
long length,
BF_KEY *schedule,
unsigned char *ivec,
int *num,
int encrypt);
This is one of the more useful functions in this Blowfish library, it
implements CFB mode of Blowfish with 64bit feedback.
This allows you to encrypt an arbitrary number of bytes,
you do not require 8 byte padding. Each call to this
routine will encrypt the input bytes to output and then update ivec
and num. Num contains 'how far' we are though ivec.
'Encrypt' is used to indicate encryption or decryption.
CFB64 mode operates by using the cipher to generate a stream
of bytes which is used to encrypt the plain text.
The cipher text is then encrypted to generate the next 64 bits to
be xored (incrementally) with the next 64 bits of plain
text. As can be seen from this, to encrypt or decrypt,
the same 'cipher stream' needs to be generated but the way the next
block of data is gathered for encryption is different for
encryption and decryption.
void BF_ofb64_encrypt(
unsigned char *in,
unsigned char *out,
long length,
BF_KEY *schedule,
unsigned char *ivec,
int *num);
This functions implements OFB mode of Blowfish with 64bit feedback.
This allows you to encrypt an arbitrary number of bytes,
you do not require 8 byte padding. Each call to this
routine will encrypt the input bytes to output and then update ivec
and num. Num contains 'how far' we are though ivec.
This is in effect a stream cipher, there is no encryption or
decryption mode.
For reading passwords, I suggest using des_read_pw_string() from my DES library.
To generate a password from a text string, I suggest using MD5 (or MD2) to
produce a 16 byte message digest that can then be passed directly to
BF_set_key().
=====
For more information about the specific Blowfish modes in this library
(ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
documentation on my DES library. What is said about DES is directly
applicable for Blowfish.
==== bn.doc ========================================================
The Big Number library.
#include "bn.h" when using this library.
This big number library was written for use in implementing the RSA and DH
public key encryption algorithms. As such, features such as negative
numbers have not been extensively tested but they should work as expected.
This library uses dynamic memory allocation for storing its data structures
and so there are no limit on the size of the numbers manipulated by these
routines but there is always the requirement to check return codes from
functions just in case a memory allocation error has occurred.
The basic object in this library is a BIGNUM. It is used to hold a single
large integer. This type should be considered opaque and fields should not
be modified or accessed directly.
typedef struct bignum_st
{
int top; /* Index of last used d. */
BN_ULONG *d; /* Pointer to an array of 'BITS2' bit chunks. */
int max; /* Size of the d array. */
int neg;
} BIGNUM;
The big number is stored in a malloced array of BN_ULONG's. A BN_ULONG can
be either 16, 32 or 64 bits in size, depending on the 'number of bits'
specified in bn.h.
The 'd' field is this array. 'max' is the size of the 'd' array that has
been allocated. 'top' is the 'last' entry being used, so for a value of 4,
bn.d[0]=4 and bn.top=1. 'neg' is 1 if the number is negative.
When a BIGNUM is '0', the 'd' field can be NULL and top == 0.
Various routines in this library require the use of 'temporary' BIGNUM
variables during their execution. Due to the use of dynamic memory
allocation to create BIGNUMs being rather expensive when used in
conjunction with repeated subroutine calls, the BN_CTX structure is
used. This structure contains BN_CTX BIGNUMs. BN_CTX
is the maximum number of temporary BIGNUMs any publicly exported
function will use.
#define BN_CTX 12
typedef struct bignum_ctx
{
int tos; /* top of stack */
BIGNUM *bn[BN_CTX]; /* The variables */
} BN_CTX;
The functions that follow have been grouped according to function. Most
arithmetic functions return a result in the first argument, sometimes this
first argument can also be an input parameter, sometimes it cannot. These
restrictions are documented.
extern BIGNUM *BN_value_one;
There is one variable defined by this library, a BIGNUM which contains the
number 1. This variable is useful for use in comparisons and assignment.
Get Size functions.
int BN_num_bits(BIGNUM *a);
This function returns the size of 'a' in bits.
int BN_num_bytes(BIGNUM *a);
This function (macro) returns the size of 'a' in bytes.
For conversion of BIGNUMs to byte streams, this is the number of
bytes the output string will occupy. If the output byte
format specifies that the 'top' bit indicates if the number is
signed, so an extra '0' byte is required if the top bit on a
positive number is being written, it is upto the application to
make this adjustment. Like I said at the start, I don't
really support negative numbers :-).
Creation/Destruction routines.
BIGNUM *BN_new();
Return a new BIGNUM object. The number initially has a value of 0. If
there is an error, NULL is returned.
void BN_free(BIGNUM *a);
Free()s a BIGNUM.
void BN_clear(BIGNUM *a);
Sets 'a' to a value of 0 and also zeros all unused allocated
memory. This function is used to clear a variable of 'sensitive'
data that was held in it.
void BN_clear_free(BIGNUM *a);
This function zeros the memory used by 'a' and then free()'s it.
This function should be used to BN_free() BIGNUMS that have held
sensitive numeric values like RSA private key values. Both this
function and BN_clear tend to only be used by RSA and DH routines.
BN_CTX *BN_CTX_new(void);
Returns a new BN_CTX. NULL on error.
void BN_CTX_free(BN_CTX *c);
Free a BN_CTX structure. The BIGNUMs in 'c' are BN_clear_free()ed.
BIGNUM *bn_expand(BIGNUM *b, int bits);
This is an internal function that should not normally be used. It
ensures that 'b' has enough room for a 'bits' bit number. It is
mostly used by the various BIGNUM routines. If there is an error,
NULL is returned. if not, 'b' is returned.
BIGNUM *BN_copy(BIGNUM *to, BIGNUM *from);
The 'from' is copied into 'to'. NULL is returned if there is an
error, otherwise 'to' is returned.
BIGNUM *BN_dup(BIGNUM *a);
A new BIGNUM is created and returned containing the value of 'a'.
NULL is returned on error.
Comparison and Test Functions.
int BN_is_zero(BIGNUM *a)
Return 1 if 'a' is zero, else 0.
int BN_is_one(a)
Return 1 is 'a' is one, else 0.
int BN_is_word(a,w)
Return 1 if 'a' == w, else 0. 'w' is a BN_ULONG.
int BN_cmp(BIGNUM *a, BIGNUM *b);
Return -1 if 'a' is less than 'b', 0 if 'a' and 'b' are the same
and 1 is 'a' is greater than 'b'. This is a signed comparison.
int BN_ucmp(BIGNUM *a, BIGNUM *b);
This function is the same as BN_cmp except that the comparison
ignores the sign of the numbers.
Arithmetic Functions
For all of these functions, 0 is returned if there is an error and 1 is
returned for success. The return value should always be checked. eg.
if (!BN_add(r,a,b)) goto err;
Unless explicitly mentioned, the 'return' value can be one of the
'parameters' to the function.
int BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b);
Add 'a' and 'b' and return the result in 'r'. This is r=a+b.
int BN_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b);
Subtract 'a' from 'b' and put the result in 'r'. This is r=a-b.
int BN_lshift(BIGNUM *r, BIGNUM *a, int n);
Shift 'a' left by 'n' bits. This is r=a*(2^n).
int BN_lshift1(BIGNUM *r, BIGNUM *a);
Shift 'a' left by 1 bit. This form is more efficient than
BN_lshift(r,a,1). This is r=a*2.
int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
Shift 'a' right by 'n' bits. This is r=int(a/(2^n)).
int BN_rshift1(BIGNUM *r, BIGNUM *a);
Shift 'a' right by 1 bit. This form is more efficient than
BN_rshift(r,a,1). This is r=int(a/2).
int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b);
Multiply a by b and return the result in 'r'. 'r' must not be
either 'a' or 'b'. It has to be a different BIGNUM.
This is r=a*b.
int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
Multiply a by a and return the result in 'r'. 'r' must not be
'a'. This function is alot faster than BN_mul(r,a,a). This is r=a*a.
int BN_div(BIGNUM *dv, BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx);
Divide 'm' by 'd' and return the result in 'dv' and the remainder
in 'rem'. Either of 'dv' or 'rem' can be NULL in which case that
value is not returned. 'ctx' needs to be passed as a source of
temporary BIGNUM variables.
This is dv=int(m/d), rem=m%d.
int BN_mod(BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx);
Find the remainder of 'm' divided by 'd' and return it in 'rem'.
'ctx' holds the temporary BIGNUMs required by this function.
This function is more efficient than BN_div(NULL,rem,m,d,ctx);
This is rem=m%d.
int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BIGNUM *m,BN_CTX *ctx);
Multiply 'a' by 'b' and return the remainder when divided by 'm'.
'ctx' holds the temporary BIGNUMs required by this function.
This is r=(a*b)%m.
int BN_mod_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BIGNUM *m,BN_CTX *ctx);
Raise 'a' to the 'p' power and return the remainder when divided by
'm'. 'ctx' holds the temporary BIGNUMs required by this function.
This is r=(a^p)%m.
int BN_reciprocal(BIGNUM *r, BIGNUM *m, BN_CTX *ctx);
Return the reciprocal of 'm'. 'ctx' holds the temporary variables
required. This function returns -1 on error, otherwise it returns
the number of bits 'r' is shifted left to make 'r' into an integer.
This number of bits shifted is required in BN_mod_mul_reciprocal().
This is r=(1/m)<<(BN_num_bits(m)+1).
int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *x, BIGNUM *y, BIGNUM *m,
BIGNUM *i, int nb, BN_CTX *ctx);
This function is used to perform an efficient BN_mod_mul()
operation. If one is going to repeatedly perform BN_mod_mul() with
the same modulus is worth calculating the reciprocal of the modulus
and then using this function. This operation uses the fact that
a/b == a*r where r is the reciprocal of b. On modern computers
multiplication is very fast and big number division is very slow.
'x' is multiplied by 'y' and then divided by 'm' and the remainder
is returned. 'i' is the reciprocal of 'm' and 'nb' is the number
of bits as returned from BN_reciprocal(). Normal usage is as follows.
bn=BN_reciprocal(i,m);
for (...)
{ BN_mod_mul_reciprocal(r,x,y,m,i,bn,ctx); }
This is r=(x*y)%m. Internally it is approximately
r=(x*y)-m*(x*y/m) or r=(x*y)-m*((x*y*i) >> bn)
This function is used in BN_mod_exp() and BN_is_prime().
Assignment Operations
int BN_one(BIGNUM *a)
Set 'a' to hold the value one.
This is a=1.
int BN_zero(BIGNUM *a)
Set 'a' to hold the value zero.
This is a=0.
int BN_set_word(BIGNUM *a, unsigned long w);
Set 'a' to hold the value of 'w'. 'w' is an unsigned long.
This is a=w.
unsigned long BN_get_word(BIGNUM *a);
Returns 'a' in an unsigned long. Not remarkably, often 'a' will
be bigger than a word, in which case 0xffffffffL is returned.
Word Operations
These functions are much more efficient that the normal bignum arithmetic
operations.
BN_ULONG BN_mod_word(BIGNUM *a, unsigned long w);
Return the remainder of 'a' divided by 'w'.
This is return(a%w).
int BN_add_word(BIGNUM *a, unsigned long w);
Add 'w' to 'a'. This function does not take the sign of 'a' into
account. This is a+=w;
Bit operations.
int BN_is_bit_set(BIGNUM *a, int n);
This function return 1 if bit 'n' is set in 'a' else 0.
int BN_set_bit(BIGNUM *a, int n);
This function sets bit 'n' to 1 in 'a'.
This is a&= ~(1<<n);
int BN_clear_bit(BIGNUM *a, int n);
This function sets bit 'n' to zero in 'a'. Return 0 if less
than 'n' bits in 'a' else 1. This is a&= ~(1<<n);
int BN_mask_bits(BIGNUM *a, int n);
Truncate 'a' to n bits long. This is a&= ~((~0)<<n)
Format conversion routines.
BIGNUM *BN_bin2bn(unsigned char *s, int len,BIGNUM *ret);
This function converts 'len' bytes in 's' into a BIGNUM which
is put in 'ret'. If ret is NULL, a new BIGNUM is created.
Either this new BIGNUM or ret is returned. The number is
assumed to be in bigendian form in 's'. By this I mean that
to 'ret' is created as follows for 'len' == 5.
ret = s[0]*2^32 + s[1]*2^24 + s[2]*2^16 + s[3]*2^8 + s[4];
This function cannot be used to convert negative numbers. It
is always assumed the number is positive. The application
needs to diddle the 'neg' field of th BIGNUM its self.
The better solution would be to save the numbers in ASN.1 format
since this is a defined standard for storing big numbers.
Look at the functions
ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai);
BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn);
int i2d_ASN1_INTEGER(ASN1_INTEGER *a,unsigned char **pp);
ASN1_INTEGER *d2i_ASN1_INTEGER(ASN1_INTEGER **a,unsigned char **pp,
long length;
int BN_bn2bin(BIGNUM *a, unsigned char *to);
This function converts 'a' to a byte string which is put into
'to'. The representation is big-endian in that the most
significant byte of 'a' is put into to[0]. This function
returns the number of bytes used to hold 'a'. BN_num_bytes(a)
would return the same value and can be used to determine how
large 'to' needs to be. If the number is negative, this
information is lost. Since this library was written to
manipulate large positive integers, the inability to save and
restore them is not considered to be a problem by me :-).
As for BN_bin2bn(), look at the ASN.1 integer encoding funtions
for SSLeay. They use BN_bin2bn() and BN_bn2bin() internally.
char *BN_bn2ascii(BIGNUM *a);
This function returns a malloc()ed string that contains the
ascii hexadecimal encoding of 'a'. The number is in bigendian
format with a '-' in front if the number is negative.
int BN_ascii2bn(BIGNUM **bn, char *a);
The inverse of BN_bn2ascii. The function returns the number of
characters from 'a' were processed in generating a the bignum.
error is inticated by 0 being returned. The number is a
hex digit string, optionally with a leading '-'. If *bn
is null, a BIGNUM is created and returned via that variable.
int BN_print_fp(FILE *fp, BIGNUM *a);
'a' is printed to file pointer 'fp'. It is in the same format
that is output from BN_bn2ascii(). 0 is returned on error,
1 if things are ok.
int BN_print(BIO *bp, BIGNUM *a);
Same as BN_print except that the output is done to the SSLeay libraries
BIO routines. BN_print_fp() actually calls this function.
Miscellaneous Routines.
int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
This function returns in 'rnd' a random BIGNUM that is bits
long. If bottom is 1, the number returned is odd. If top is set,
the top 2 bits of the number are set. This is useful because if
this is set, 2 'n; bit numbers multiplied together will return a 2n
bit number. If top was not set, they could produce a 2n-1 bit
number.
BIGNUM *BN_mod_inverse(BIGNUM *a, BIGNUM *n,BN_CTX *ctx);
This function create a new BIGNUM and returns it. This number
is the inverse mod 'n' of 'a'. By this it is meant that the
returned value 'r' satisfies (a*r)%n == 1. This function is
used in the generation of RSA keys. 'ctx', as per usual,
is used to hold temporary variables that are required by the
function. NULL is returned on error.
int BN_gcd(BIGNUM *r,BIGNUM *a,BIGNUM *b,BN_CTX *ctx);
'r' has the greatest common divisor of 'a' and 'b'. 'ctx' is
used for temporary variables and 0 is returned on error.
int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(),BN_CTX *ctx,
char *cb_arg);
This function is used to check if a BIGNUM ('p') is prime.
It performs this test by using the Miller-Rabin randomised
primality test. This is a probalistic test that requires a
number of rounds to ensure the number is prime to a high
degree of probability. Since this can take quite some time, a
callback function can be passed and it will be called each
time 'p' passes a round of the prime testing. 'callback' will
be called as follows, callback(1,n,cb_arg) where n is the number of
the round, just passed. As per usual 'ctx' contains temporary
variables used. If ctx is NULL, it does not matter, a local version
will be malloced. This parameter is present to save some mallocing
inside the function but probably could be removed.
0 is returned on error.
'ncheck' is the number of Miller-Rabin tests to run. It is
suggested to use the value 'BN_prime_checks' by default.
BIGNUM *BN_generate_prime(
int bits,
int strong,
BIGNUM *a,
BIGNUM *rems,
void (*callback)());
char *cb_arg
This function is used to generate prime numbers. It returns a
new BIGNUM that has a high probability of being a prime.
'bits' is the number of bits that
are to be in the prime. If 'strong' is true, the returned prime
will also be a strong prime ((p-1)/2 is also prime).
While searching for the prime ('p'), we
can add the requirement that the prime fill the following
condition p%a == rem. This can be used to help search for
primes with specific features, which is required when looking
for primes suitable for use with certain 'g' values in the
Diffie-Hellman key exchange algorithm. If 'a' is NULL,
this condition is not checked. If rem is NULL, rem is assumed
to be 1. Since this search for a prime
can take quite some time, if callback is not NULL, it is called
in the following situations.
We have a suspected prime (from a quick sieve),
callback(0,sus_prime++,cb_arg). Each item to be passed to BN_is_prime().
callback(1,round++,cb_arg). Each successful 'round' in BN_is_prime().
callback(2,round,cb_arg). For each successful BN_is_prime() test.
Hints
-----
DSA wants 64*32 to use word mont mul, but RSA wants to use full.
==== callback.doc ========================================================
Callback functions used in SSLeay.
--------------------------
The BIO library.
Each BIO structure can have a callback defined against it. This callback is
called 2 times for each BIO 'function'. It is passed 6 parameters.
BIO_debug_callback() is an example callback which is defined in
crypto/buffer/bio_cb.c and is used in apps/dgst.c This is intended mostly
for debuging or to notify the application of IO.
long BIO_debug_callback(BIO *bio,int cmd,char *argp,int argi,long argl,
long ret);
bio is the BIO being called, cmd is the type of BIO function being called.
Look at the BIO_CB_* defines in buffer.h. Argp and argi are the arguments
passed to BIO_read(), BIO_write, BIO_gets(), BIO_puts(). In the case of
BIO_ctrl(), argl is also defined. The first time the callback is called,
before the underlying function has been executed, 0 is passed as 'ret', and
if the return code from the callback is not > 0, the call is aborted
and the returned <= 0 value is returned.
The second time the callback is called, the 'cmd' value also has
BIO_CB_RETURN logically 'or'ed with it. The 'ret' value is the value returned
from the actuall function call and whatever the callback returns is returned
from the BIO function.
BIO_set_callback(b,cb) can be used to set the callback function
(b is a BIO), and BIO_set_callback_arg(b,arg) can be used to
set the cb_arg argument in the BIO strucutre. This field is only intended
to be used by application, primarily in the callback function since it is
accessable since the BIO is passed.
--------------------------
The PEM library.
The pem library only really uses one type of callback,
static int def_callback(char *buf, int num, int verify);
which is used to return a password string if required.
'buf' is the buffer to put the string in. 'num' is the size of 'buf'
and 'verify' is used to indicate that the password should be checked.