tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
crypto: doc - AEAD / RNG AF_ALG interface
The patch moves the information provided in
Documentation/crypto/crypto-API-userspace.txt into a separate chapter in
the kernel crypto API DocBook. Some corrections are applied (such as
removing a reference to Netlink when the AF_ALG socket is referred to).
In addition, the AEAD and RNG interface description is now added.
Also, a brief description of the zero-copy interface with an example
code snippet is provided.
Signed-off-by: Stephan Mueller <smueller@chronox.de>
Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>
authored by
Stephan Mueller
and committed by
Herbert Xu
dbe5fe7e
cde001e4
+596
-205
+596
Documentation/DocBook/crypto-API.tmpl
+596
Documentation/DocBook/crypto-API.tmpl
···
1072
1072
</sect1>
1073
1073
</chapter>
1074
1074
1075
+
<chapter id="User"><title>User Space Interface</title>
1076
+
<sect1><title>Introduction</title>
1077
+
<para>
1078
+
The concepts of the kernel crypto API visible to kernel space is fully
1079
+
applicable to the user space interface as well. Therefore, the kernel
1080
+
crypto API high level discussion for the in-kernel use cases applies
1081
+
here as well.
1082
+
</para>
1083
+
1084
+
<para>
1085
+
The major difference, however, is that user space can only act as a
1086
+
consumer and never as a provider of a transformation or cipher algorithm.
1087
+
</para>
1088
+
1089
+
<para>
1090
+
The following covers the user space interface exported by the kernel
1091
+
crypto API. A working example of this description is libkcapi that
1092
+
can be obtained from [1]. That library can be used by user space
1093
+
applications that require cryptographic services from the kernel.
1094
+
</para>
1095
+
1096
+
<para>
1097
+
Some details of the in-kernel kernel crypto API aspects do not
1098
+
apply to user space, however. This includes the difference between
1099
+
synchronous and asynchronous invocations. The user space API call
1100
+
is fully synchronous.
1101
+
</para>
1102
+
1103
+
<para>
1104
+
[1] http://www.chronox.de/libkcapi.html
1105
+
</para>
1106
+
1107
+
</sect1>
1108
+
1109
+
<sect1><title>User Space API General Remarks</title>
1110
+
<para>
1111
+
The kernel crypto API is accessible from user space. Currently,
1112
+
the following ciphers are accessible:
1113
+
</para>
1114
+
1115
+
<itemizedlist>
1116
+
<listitem>
1117
+
<para>Message digest including keyed message digest (HMAC, CMAC)</para>
1118
+
</listitem>
1119
+
1120
+
<listitem>
1121
+
<para>Symmetric ciphers</para>
1122
+
</listitem>
1123
+
1124
+
<listitem>
1125
+
<para>AEAD ciphers</para>
1126
+
</listitem>
1127
+
1128
+
<listitem>
1129
+
<para>Random Number Generators</para>
1130
+
</listitem>
1131
+
</itemizedlist>
1132
+
1133
+
<para>
1134
+
The interface is provided via socket type using the type AF_ALG.
1135
+
In addition, the setsockopt option type is SOL_ALG. In case the
1136
+
user space header files do not export these flags yet, use the
1137
+
following macros:
1138
+
</para>
1139
+
1140
+
<programlisting>
1141
+
#ifndef AF_ALG
1142
+
#define AF_ALG 38
1143
+
#endif
1144
+
#ifndef SOL_ALG
1145
+
#define SOL_ALG 279
1146
+
#endif
1147
+
</programlisting>
1148
+
1149
+
<para>
1150
+
A cipher is accessed with the same name as done for the in-kernel
1151
+
API calls. This includes the generic vs. unique naming schema for
1152
+
ciphers as well as the enforcement of priorities for generic names.
1153
+
</para>
1154
+
1155
+
<para>
1156
+
To interact with the kernel crypto API, a socket must be
1157
+
created by the user space application. User space invokes the cipher
1158
+
operation with the send()/write() system call family. The result of the
1159
+
cipher operation is obtained with the read()/recv() system call family.
1160
+
</para>
1161
+
1162
+
<para>
1163
+
The following API calls assume that the socket descriptor
1164
+
is already opened by the user space application and discusses only
1165
+
the kernel crypto API specific invocations.
1166
+
</para>
1167
+
1168
+
<para>
1169
+
To initialize the socket interface, the following sequence has to
1170
+
be performed by the consumer:
1171
+
</para>
1172
+
1173
+
<orderedlist>
1174
+
<listitem>
1175
+
<para>
1176
+
Create a socket of type AF_ALG with the struct sockaddr_alg
1177
+
parameter specified below for the different cipher types.
1178
+
</para>
1179
+
</listitem>
1180
+
1181
+
<listitem>
1182
+
<para>
1183
+
Invoke bind with the socket descriptor
1184
+
</para>
1185
+
</listitem>
1186
+
1187
+
<listitem>
1188
+
<para>
1189
+
Invoke accept with the socket descriptor. The accept system call
1190
+
returns a new file descriptor that is to be used to interact with
1191
+
the particular cipher instance. When invoking send/write or recv/read
1192
+
system calls to send data to the kernel or obtain data from the
1193
+
kernel, the file descriptor returned by accept must be used.
1194
+
</para>
1195
+
</listitem>
1196
+
</orderedlist>
1197
+
</sect1>
1198
+
1199
+
<sect1><title>In-place Cipher operation</title>
1200
+
<para>
1201
+
Just like the in-kernel operation of the kernel crypto API, the user
1202
+
space interface allows the cipher operation in-place. That means that
1203
+
the input buffer used for the send/write system call and the output
1204
+
buffer used by the read/recv system call may be one and the same.
1205
+
This is of particular interest for symmetric cipher operations where a
1206
+
copying of the output data to its final destination can be avoided.
1207
+
</para>
1208
+
1209
+
<para>
1210
+
If a consumer on the other hand wants to maintain the plaintext and
1211
+
the ciphertext in different memory locations, all a consumer needs
1212
+
to do is to provide different memory pointers for the encryption and
1213
+
decryption operation.
1214
+
</para>
1215
+
</sect1>
1216
+
1217
+
<sect1><title>Message Digest API</title>
1218
+
<para>
1219
+
The message digest type to be used for the cipher operation is
1220
+
selected when invoking the bind syscall. bind requires the caller
1221
+
to provide a filled struct sockaddr data structure. This data
1222
+
structure must be filled as follows:
1223
+
</para>
1224
+
1225
+
<programlisting>
1226
+
struct sockaddr_alg sa = {
1227
+
.salg_family = AF_ALG,
1228
+
.salg_type = "hash", /* this selects the hash logic in the kernel */
1229
+
.salg_name = "sha1" /* this is the cipher name */
1230
+
};
1231
+
</programlisting>
1232
+
1233
+
<para>
1234
+
The salg_type value "hash" applies to message digests and keyed
1235
+
message digests. Though, a keyed message digest is referenced by
1236
+
the appropriate salg_name. Please see below for the setsockopt
1237
+
interface that explains how the key can be set for a keyed message
1238
+
digest.
1239
+
</para>
1240
+
1241
+
<para>
1242
+
Using the send() system call, the application provides the data that
1243
+
should be processed with the message digest. The send system call
1244
+
allows the following flags to be specified:
1245
+
</para>
1246
+
1247
+
<itemizedlist>
1248
+
<listitem>
1249
+
<para>
1250
+
MSG_MORE: If this flag is set, the send system call acts like a
1251
+
message digest update function where the final hash is not
1252
+
yet calculated. If the flag is not set, the send system call
1253
+
calculates the final message digest immediately.
1254
+
</para>
1255
+
</listitem>
1256
+
</itemizedlist>
1257
+
1258
+
<para>
1259
+
With the recv() system call, the application can read the message
1260
+
digest from the kernel crypto API. If the buffer is too small for the
1261
+
message digest, the flag MSG_TRUNC is set by the kernel.
1262
+
</para>
1263
+
1264
+
<para>
1265
+
In order to set a message digest key, the calling application must use
1266
+
the setsockopt() option of ALG_SET_KEY. If the key is not set the HMAC
1267
+
operation is performed without the initial HMAC state change caused by
1268
+
the key.
1269
+
</para>
1270
+
</sect1>
1271
+
1272
+
<sect1><title>Symmetric Cipher API</title>
1273
+
<para>
1274
+
The operation is very similar to the message digest discussion.
1275
+
During initialization, the struct sockaddr data structure must be
1276
+
filled as follows:
1277
+
</para>
1278
+
1279
+
<programlisting>
1280
+
struct sockaddr_alg sa = {
1281
+
.salg_family = AF_ALG,
1282
+
.salg_type = "skcipher", /* this selects the symmetric cipher */
1283
+
.salg_name = "cbc(aes)" /* this is the cipher name */
1284
+
};
1285
+
</programlisting>
1286
+
1287
+
<para>
1288
+
Before data can be sent to the kernel using the write/send system
1289
+
call family, the consumer must set the key. The key setting is
1290
+
described with the setsockopt invocation below.
1291
+
</para>
1292
+
1293
+
<para>
1294
+
Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is
1295
+
specified with the data structure provided by the sendmsg() system call.
1296
+
</para>
1297
+
1298
+
<para>
1299
+
The sendmsg system call parameter of struct msghdr is embedded into the
1300
+
struct cmsghdr data structure. See recv(2) and cmsg(3) for more
1301
+
information on how the cmsghdr data structure is used together with the
1302
+
send/recv system call family. That cmsghdr data structure holds the
1303
+
following information specified with a separate header instances:
1304
+
</para>
1305
+
1306
+
<itemizedlist>
1307
+
<listitem>
1308
+
<para>
1309
+
specification of the cipher operation type with one of these flags:
1310
+
</para>
1311
+
<itemizedlist>
1312
+
<listitem>
1313
+
<para>ALG_OP_ENCRYPT - encryption of data</para>
1314
+
</listitem>
1315
+
<listitem>
1316
+
<para>ALG_OP_DECRYPT - decryption of data</para>
1317
+
</listitem>
1318
+
</itemizedlist>
1319
+
</listitem>
1320
+
1321
+
<listitem>
1322
+
<para>
1323
+
specification of the IV information marked with the flag ALG_SET_IV
1324
+
</para>
1325
+
</listitem>
1326
+
</itemizedlist>
1327
+
1328
+
<para>
1329
+
The send system call family allows the following flag to be specified:
1330
+
</para>
1331
+
1332
+
<itemizedlist>
1333
+
<listitem>
1334
+
<para>
1335
+
MSG_MORE: If this flag is set, the send system call acts like a
1336
+
cipher update function where more input data is expected
1337
+
with a subsequent invocation of the send system call.
1338
+
</para>
1339
+
</listitem>
1340
+
</itemizedlist>
1341
+
1342
+
<para>
1343
+
Note: The kernel reports -EINVAL for any unexpected data. The caller
1344
+
must make sure that all data matches the constraints given in
1345
+
/proc/crypto for the selected cipher.
1346
+
</para>
1347
+
1348
+
<para>
1349
+
With the recv() system call, the application can read the result of
1350
+
the cipher operation from the kernel crypto API. The output buffer
1351
+
must be at least as large as to hold all blocks of the encrypted or
1352
+
decrypted data. If the output data size is smaller, only as many
1353
+
blocks are returned that fit into that output buffer size.
1354
+
</para>
1355
+
</sect1>
1356
+
1357
+
<sect1><title>AEAD Cipher API</title>
1358
+
<para>
1359
+
The operation is very similar to the symmetric cipher discussion.
1360
+
During initialization, the struct sockaddr data structure must be
1361
+
filled as follows:
1362
+
</para>
1363
+
1364
+
<programlisting>
1365
+
struct sockaddr_alg sa = {
1366
+
.salg_family = AF_ALG,
1367
+
.salg_type = "aead", /* this selects the symmetric cipher */
1368
+
.salg_name = "gcm(aes)" /* this is the cipher name */
1369
+
};
1370
+
</programlisting>
1371
+
1372
+
<para>
1373
+
Before data can be sent to the kernel using the write/send system
1374
+
call family, the consumer must set the key. The key setting is
1375
+
described with the setsockopt invocation below.
1376
+
</para>
1377
+
1378
+
<para>
1379
+
In addition, before data can be sent to the kernel using the
1380
+
write/send system call family, the consumer must set the authentication
1381
+
tag size. To set the authentication tag size, the caller must use the
1382
+
setsockopt invocation described below.
1383
+
</para>
1384
+
1385
+
<para>
1386
+
Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is
1387
+
specified with the data structure provided by the sendmsg() system call.
1388
+
</para>
1389
+
1390
+
<para>
1391
+
The sendmsg system call parameter of struct msghdr is embedded into the
1392
+
struct cmsghdr data structure. See recv(2) and cmsg(3) for more
1393
+
information on how the cmsghdr data structure is used together with the
1394
+
send/recv system call family. That cmsghdr data structure holds the
1395
+
following information specified with a separate header instances:
1396
+
</para>
1397
+
1398
+
<itemizedlist>
1399
+
<listitem>
1400
+
<para>
1401
+
specification of the cipher operation type with one of these flags:
1402
+
</para>
1403
+
<itemizedlist>
1404
+
<listitem>
1405
+
<para>ALG_OP_ENCRYPT - encryption of data</para>
1406
+
</listitem>
1407
+
<listitem>
1408
+
<para>ALG_OP_DECRYPT - decryption of data</para>
1409
+
</listitem>
1410
+
</itemizedlist>
1411
+
</listitem>
1412
+
1413
+
<listitem>
1414
+
<para>
1415
+
specification of the IV information marked with the flag ALG_SET_IV
1416
+
</para>
1417
+
</listitem>
1418
+
1419
+
<listitem>
1420
+
<para>
1421
+
specification of the associated authentication data (AAD) with the
1422
+
flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together
1423
+
with the plaintext / ciphertext. See below for the memory structure.
1424
+
</para>
1425
+
</listitem>
1426
+
</itemizedlist>
1427
+
1428
+
<para>
1429
+
The send system call family allows the following flag to be specified:
1430
+
</para>
1431
+
1432
+
<itemizedlist>
1433
+
<listitem>
1434
+
<para>
1435
+
MSG_MORE: If this flag is set, the send system call acts like a
1436
+
cipher update function where more input data is expected
1437
+
with a subsequent invocation of the send system call.
1438
+
</para>
1439
+
</listitem>
1440
+
</itemizedlist>
1441
+
1442
+
<para>
1443
+
Note: The kernel reports -EINVAL for any unexpected data. The caller
1444
+
must make sure that all data matches the constraints given in
1445
+
/proc/crypto for the selected cipher.
1446
+
</para>
1447
+
1448
+
<para>
1449
+
With the recv() system call, the application can read the result of
1450
+
the cipher operation from the kernel crypto API. The output buffer
1451
+
must be at least as large as defined with the memory structure below.
1452
+
If the output data size is smaller, the cipher operation is not performed.
1453
+
</para>
1454
+
1455
+
<para>
1456
+
The authenticated decryption operation may indicate an integrity error.
1457
+
Such breach in integrity is marked with the -EBADMSG error code.
1458
+
</para>
1459
+
1460
+
<sect2><title>AEAD Memory Structure</title>
1461
+
<para>
1462
+
The AEAD cipher operates with the following information that
1463
+
is communicated between user and kernel space as one data stream:
1464
+
</para>
1465
+
1466
+
<itemizedlist>
1467
+
<listitem>
1468
+
<para>plaintext or ciphertext</para>
1469
+
</listitem>
1470
+
1471
+
<listitem>
1472
+
<para>associated authentication data (AAD)</para>
1473
+
</listitem>
1474
+
1475
+
<listitem>
1476
+
<para>authentication tag</para>
1477
+
</listitem>
1478
+
</itemizedlist>
1479
+
1480
+
<para>
1481
+
The sizes of the AAD and the authentication tag are provided with
1482
+
the sendmsg and setsockopt calls (see there). As the kernel knows
1483
+
the size of the entire data stream, the kernel is now able to
1484
+
calculate the right offsets of the data components in the data
1485
+
stream.
1486
+
</para>
1487
+
1488
+
<para>
1489
+
The user space caller must arrange the aforementioned information
1490
+
in the following order:
1491
+
</para>
1492
+
1493
+
<itemizedlist>
1494
+
<listitem>
1495
+
<para>
1496
+
AEAD encryption input: AAD || plaintext
1497
+
</para>
1498
+
</listitem>
1499
+
1500
+
<listitem>
1501
+
<para>
1502
+
AEAD decryption input: AAD || ciphertext || authentication tag
1503
+
</para>
1504
+
</listitem>
1505
+
</itemizedlist>
1506
+
1507
+
<para>
1508
+
The output buffer the user space caller provides must be at least as
1509
+
large to hold the following data:
1510
+
</para>
1511
+
1512
+
<itemizedlist>
1513
+
<listitem>
1514
+
<para>
1515
+
AEAD encryption output: ciphertext || authentication tag
1516
+
</para>
1517
+
</listitem>
1518
+
1519
+
<listitem>
1520
+
<para>
1521
+
AEAD decryption output: plaintext
1522
+
</para>
1523
+
</listitem>
1524
+
</itemizedlist>
1525
+
</sect2>
1526
+
</sect1>
1527
+
1528
+
<sect1><title>Random Number Generator API</title>
1529
+
<para>
1530
+
Again, the operation is very similar to the other APIs.
1531
+
During initialization, the struct sockaddr data structure must be
1532
+
filled as follows:
1533
+
</para>
1534
+
1535
+
<programlisting>
1536
+
struct sockaddr_alg sa = {
1537
+
.salg_family = AF_ALG,
1538
+
.salg_type = "rng", /* this selects the symmetric cipher */
1539
+
.salg_name = "drbg_nopr_sha256" /* this is the cipher name */
1540
+
};
1541
+
</programlisting>
1542
+
1543
+
<para>
1544
+
Depending on the RNG type, the RNG must be seeded. The seed is provided
1545
+
using the setsockopt interface to set the key. For example, the
1546
+
ansi_cprng requires a seed. The DRBGs do not require a seed, but
1547
+
may be seeded.
1548
+
</para>
1549
+
1550
+
<para>
1551
+
Using the read()/recvmsg() system calls, random numbers can be obtained.
1552
+
The kernel generates at most 128 bytes in one call. If user space
1553
+
requires more data, multiple calls to read()/recvmsg() must be made.
1554
+
</para>
1555
+
1556
+
<para>
1557
+
WARNING: The user space caller may invoke the initially mentioned
1558
+
accept system call multiple times. In this case, the returned file
1559
+
descriptors have the same state.
1560
+
</para>
1561
+
1562
+
</sect1>
1563
+
1564
+
<sect1><title>Zero-Copy Interface</title>
1565
+
<para>
1566
+
In addition to the send/write/read/recv system call familty, the AF_ALG
1567
+
interface can be accessed with the zero-copy interface of splice/vmsplice.
1568
+
As the name indicates, the kernel tries to avoid a copy operation into
1569
+
kernel space.
1570
+
</para>
1571
+
1572
+
<para>
1573
+
The zero-copy operation requires data to be aligned at the page boundary.
1574
+
Non-aligned data can be used as well, but may require more operations of
1575
+
the kernel which would defeat the speed gains obtained from the zero-copy
1576
+
interface.
1577
+
</para>
1578
+
1579
+
<para>
1580
+
The system-interent limit for the size of one zero-copy operation is
1581
+
16 pages. If more data is to be sent to AF_ALG, user space must slice
1582
+
the input into segments with a maximum size of 16 pages.
1583
+
</para>
1584
+
1585
+
<para>
1586
+
Zero-copy can be used with the following code example (a complete working
1587
+
example is provided with libkcapi):
1588
+
</para>
1589
+
1590
+
<programlisting>
1591
+
int pipes[2];
1592
+
1593
+
pipe(pipes);
1594
+
/* input data in iov */
1595
+
vmsplice(pipes[1], iov, iovlen, SPLICE_F_GIFT);
1596
+
/* opfd is the file descriptor returned from accept() system call */
1597
+
splice(pipes[0], NULL, opfd, NULL, ret, 0);
1598
+
read(opfd, out, outlen);
1599
+
</programlisting>
1600
+
1601
+
</sect1>
1602
+
1603
+
<sect1><title>Setsockopt Interface</title>
1604
+
<para>
1605
+
In addition to the read/recv and send/write system call handling
1606
+
to send and retrieve data subject to the cipher operation, a consumer
1607
+
also needs to set the additional information for the cipher operation.
1608
+
This additional information is set using the setsockopt system call
1609
+
that must be invoked with the file descriptor of the open cipher
1610
+
(i.e. the file descriptor returned by the accept system call).
1611
+
</para>
1612
+
1613
+
<para>
1614
+
Each setsockopt invocation must use the level SOL_ALG.
1615
+
</para>
1616
+
1617
+
<para>
1618
+
The setsockopt interface allows setting the following data using
1619
+
the mentioned optname:
1620
+
</para>
1621
+
1622
+
<itemizedlist>
1623
+
<listitem>
1624
+
<para>
1625
+
ALG_SET_KEY -- Setting the key. Key setting is applicable to:
1626
+
</para>
1627
+
<itemizedlist>
1628
+
<listitem>
1629
+
<para>the skcipher cipher type (symmetric ciphers)</para>
1630
+
</listitem>
1631
+
<listitem>
1632
+
<para>the hash cipher type (keyed message digests)</para>
1633
+
</listitem>
1634
+
<listitem>
1635
+
<para>the AEAD cipher type</para>
1636
+
</listitem>
1637
+
<listitem>
1638
+
<para>the RNG cipher type to provide the seed</para>
1639
+
</listitem>
1640
+
</itemizedlist>
1641
+
</listitem>
1642
+
1643
+
<listitem>
1644
+
<para>
1645
+
ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size
1646
+
for AEAD ciphers. For a encryption operation, the authentication
1647
+
tag of the given size will be generated. For a decryption operation,
1648
+
the provided ciphertext is assumed to contain an authentication tag
1649
+
of the given size (see section about AEAD memory layout below).
1650
+
</para>
1651
+
</listitem>
1652
+
</itemizedlist>
1653
+
1654
+
</sect1>
1655
+
1656
+
<sect1><title>User space API example</title>
1657
+
<para>
1658
+
Please see [1] for libkcapi which provides an easy-to-use wrapper
1659
+
around the aforementioned Netlink kernel interface. [1] also contains
1660
+
a test application that invokes all libkcapi API calls.
1661
+
</para>
1662
+
1663
+
<para>
1664
+
[1] http://www.chronox.de/libkcapi.html
1665
+
</para>
1666
+
1667
+
</sect1>
1668
+
1669
+
</chapter>
1670
+
1075
1671
<chapter id="API"><title>Programming Interface</title>
1076
1672
<sect1><title>Block Cipher Context Data Structures</title>
1077
1673
!Pinclude/linux/crypto.h Block Cipher Context Data Structures
-205
Documentation/crypto/crypto-API-userspace.txt
-205
Documentation/crypto/crypto-API-userspace.txt
···
1
-
Introduction
2
-
============
3
-
4
-
The concepts of the kernel crypto API visible to kernel space is fully
5
-
applicable to the user space interface as well. Therefore, the kernel crypto API
6
-
high level discussion for the in-kernel use cases applies here as well.
7
-
8
-
The major difference, however, is that user space can only act as a consumer
9
-
and never as a provider of a transformation or cipher algorithm.
10
-
11
-
The following covers the user space interface exported by the kernel crypto
12
-
API. A working example of this description is libkcapi that can be obtained from
13
-
[1]. That library can be used by user space applications that require
14
-
cryptographic services from the kernel.
15
-
16
-
Some details of the in-kernel kernel crypto API aspects do not
17
-
apply to user space, however. This includes the difference between synchronous
18
-
and asynchronous invocations. The user space API call is fully synchronous.
19
-
In addition, only a subset of all cipher types are available as documented
20
-
below.
21
-
22
-
23
-
User space API general remarks
24
-
==============================
25
-
26
-
The kernel crypto API is accessible from user space. Currently, the following
27
-
ciphers are accessible:
28
-
29
-
* Message digest including keyed message digest (HMAC, CMAC)
30
-
31
-
* Symmetric ciphers
32
-
33
-
Note, AEAD ciphers are currently not supported via the symmetric cipher
34
-
interface.
35
-
36
-
The interface is provided via Netlink using the type AF_ALG. In addition, the
37
-
setsockopt option type is SOL_ALG. In case the user space header files do not
38
-
export these flags yet, use the following macros:
39
-
40
-
#ifndef AF_ALG
41
-
#define AF_ALG 38
42
-
#endif
43
-
#ifndef SOL_ALG
44
-
#define SOL_ALG 279
45
-
#endif
46
-
47
-
A cipher is accessed with the same name as done for the in-kernel API calls.
48
-
This includes the generic vs. unique naming schema for ciphers as well as the
49
-
enforcement of priorities for generic names.
50
-
51
-
To interact with the kernel crypto API, a Netlink socket must be created by
52
-
the user space application. User space invokes the cipher operation with the
53
-
send/write system call family. The result of the cipher operation is obtained
54
-
with the read/recv system call family.
55
-
56
-
The following API calls assume that the Netlink socket descriptor is already
57
-
opened by the user space application and discusses only the kernel crypto API
58
-
specific invocations.
59
-
60
-
To initialize a Netlink interface, the following sequence has to be performed
61
-
by the consumer:
62
-
63
-
1. Create a socket of type AF_ALG with the struct sockaddr_alg parameter
64
-
specified below for the different cipher types.
65
-
66
-
2. Invoke bind with the socket descriptor
67
-
68
-
3. Invoke accept with the socket descriptor. The accept system call
69
-
returns a new file descriptor that is to be used to interact with
70
-
the particular cipher instance. When invoking send/write or recv/read
71
-
system calls to send data to the kernel or obtain data from the
72
-
kernel, the file descriptor returned by accept must be used.
73
-
74
-
In-place cipher operation
75
-
=========================
76
-
77
-
Just like the in-kernel operation of the kernel crypto API, the user space
78
-
interface allows the cipher operation in-place. That means that the input buffer
79
-
used for the send/write system call and the output buffer used by the read/recv
80
-
system call may be one and the same. This is of particular interest for
81
-
symmetric cipher operations where a copying of the output data to its final
82
-
destination can be avoided.
83
-
84
-
If a consumer on the other hand wants to maintain the plaintext and the
85
-
ciphertext in different memory locations, all a consumer needs to do is to
86
-
provide different memory pointers for the encryption and decryption operation.
87
-
88
-
Message digest API
89
-
==================
90
-
91
-
The message digest type to be used for the cipher operation is selected when
92
-
invoking the bind syscall. bind requires the caller to provide a filled
93
-
struct sockaddr data structure. This data structure must be filled as follows:
94
-
95
-
struct sockaddr_alg sa = {
96
-
.salg_family = AF_ALG,
97
-
.salg_type = "hash", /* this selects the hash logic in the kernel */
98
-
.salg_name = "sha1" /* this is the cipher name */
99
-
};
100
-
101
-
The salg_type value "hash" applies to message digests and keyed message digests.
102
-
Though, a keyed message digest is referenced by the appropriate salg_name.
103
-
Please see below for the setsockopt interface that explains how the key can be
104
-
set for a keyed message digest.
105
-
106
-
Using the send() system call, the application provides the data that should be
107
-
processed with the message digest. The send system call allows the following
108
-
flags to be specified:
109
-
110
-
* MSG_MORE: If this flag is set, the send system call acts like a
111
-
message digest update function where the final hash is not
112
-
yet calculated. If the flag is not set, the send system call
113
-
calculates the final message digest immediately.
114
-
115
-
With the recv() system call, the application can read the message digest from
116
-
the kernel crypto API. If the buffer is too small for the message digest, the
117
-
flag MSG_TRUNC is set by the kernel.
118
-
119
-
In order to set a message digest key, the calling application must use the
120
-
setsockopt() option of ALG_SET_KEY. If the key is not set the HMAC operation is
121
-
performed without the initial HMAC state change caused by the key.
122
-
123
-
124
-
Symmetric cipher API
125
-
====================
126
-
127
-
The operation is very similar to the message digest discussion. During
128
-
initialization, the struct sockaddr data structure must be filled as follows:
129
-
130
-
struct sockaddr_alg sa = {
131
-
.salg_family = AF_ALG,
132
-
.salg_type = "skcipher", /* this selects the symmetric cipher */
133
-
.salg_name = "cbc(aes)" /* this is the cipher name */
134
-
};
135
-
136
-
Before data can be sent to the kernel using the write/send system call family,
137
-
the consumer must set the key. The key setting is described with the setsockopt
138
-
invocation below.
139
-
140
-
Using the sendmsg() system call, the application provides the data that should
141
-
be processed for encryption or decryption. In addition, the IV is specified
142
-
with the data structure provided by the sendmsg() system call.
143
-
144
-
The sendmsg system call parameter of struct msghdr is embedded into the
145
-
struct cmsghdr data structure. See recv(2) and cmsg(3) for more information
146
-
on how the cmsghdr data structure is used together with the send/recv system
147
-
call family. That cmsghdr data structure holds the following information
148
-
specified with a separate header instances:
149
-
150
-
* specification of the cipher operation type with one of these flags:
151
-
ALG_OP_ENCRYPT - encryption of data
152
-
ALG_OP_DECRYPT - decryption of data
153
-
154
-
* specification of the IV information marked with the flag ALG_SET_IV
155
-
156
-
The send system call family allows the following flag to be specified:
157
-
158
-
* MSG_MORE: If this flag is set, the send system call acts like a
159
-
cipher update function where more input data is expected
160
-
with a subsequent invocation of the send system call.
161
-
162
-
Note: The kernel reports -EINVAL for any unexpected data. The caller must
163
-
make sure that all data matches the constraints given in /proc/crypto for the
164
-
selected cipher.
165
-
166
-
With the recv() system call, the application can read the result of the
167
-
cipher operation from the kernel crypto API. The output buffer must be at least
168
-
as large as to hold all blocks of the encrypted or decrypted data. If the output
169
-
data size is smaller, only as many blocks are returned that fit into that
170
-
output buffer size.
171
-
172
-
Setsockopt interface
173
-
====================
174
-
175
-
In addition to the read/recv and send/write system call handling to send and
176
-
retrieve data subject to the cipher operation, a consumer also needs to set
177
-
the additional information for the cipher operation. This additional information
178
-
is set using the setsockopt system call that must be invoked with the file
179
-
descriptor of the open cipher (i.e. the file descriptor returned by the
180
-
accept system call).
181
-
182
-
Each setsockopt invocation must use the level SOL_ALG.
183
-
184
-
The setsockopt interface allows setting the following data using the mentioned
185
-
optname:
186
-
187
-
* ALG_SET_KEY -- Setting the key. Key setting is applicable to:
188
-
189
-
- the skcipher cipher type (symmetric ciphers)
190
-
191
-
- the hash cipher type (keyed message digests)
192
-
193
-
User space API example
194
-
======================
195
-
196
-
Please see [1] for libkcapi which provides an easy-to-use wrapper around the
197
-
aforementioned Netlink kernel interface. [1] also contains a test application
198
-
that invokes all libkcapi API calls.
199
-
200
-
[1] http://www.chronox.de/libkcapi.html
201
-
202
-
Author
203
-
======
204
-
205
-
Stephan Mueller <smueller@chronox.de>