Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(7)

Delta Between Two Patch Sets: Doc/library/socket.rst

Issue 27744: Add AF_ALG (Linux Kernel crypto) to socket module
Left Patch Set: Created 3 years, 6 months ago
Right Patch Set: Created 3 years, 5 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
LEFTRIGHT
1 :mod:`socket` --- Low-level networking interface 1 :mod:`socket` --- Low-level networking interface
2 ================================================ 2 ================================================
3 3
4 .. module:: socket 4 .. module:: socket
5 :synopsis: Low-level networking interface. 5 :synopsis: Low-level networking interface.
6 6
7 **Source code:** :source:`Lib/socket.py` 7 **Source code:** :source:`Lib/socket.py`
8 8
9 -------------- 9 --------------
10 10
(...skipping 115 matching lines...) Expand 10 before | Expand all | Expand 10 after
126 .. versionchanged:: 3.2 126 .. versionchanged:: 3.2
127 NetBSD and DragonFlyBSD support added. 127 NetBSD and DragonFlyBSD support added.
128 128
129 - :const:`BTPROTO_SCO` accepts ``bdaddr`` where ``bdaddr`` is a 129 - :const:`BTPROTO_SCO` accepts ``bdaddr`` where ``bdaddr`` is a
130 :class:`bytes` object containing the Bluetooth address in a 130 :class:`bytes` object containing the Bluetooth address in a
131 string format. (ex. ``b'12:23:34:45:56:67'``) This protocol is not 131 string format. (ex. ``b'12:23:34:45:56:67'``) This protocol is not
132 supported under FreeBSD. 132 supported under FreeBSD.
133 133
134 - :const:`AF_ALG` is a Linux-only socket based interface to Kernel 134 - :const:`AF_ALG` is a Linux-only socket based interface to Kernel
135 cryptography. An algorithm socket is configured with a tuple of two to four 135 cryptography. An algorithm socket is configured with a tuple of two to four
136 elements ``(type, name [, feat [, mask]])``, where: 136 elements ``(type, name [, feat [, mask]])``, where:
haypo 2016/08/29 00:11:35 feat: feature?
137 137
138 - *type* is the algorithm type as string, e.g. ``aead``, ``akcipher``, 138 - *type* is the algorithm type as string, e.g. ``aead``, ``hash``,
139 ``hash``, ``skcipher`` or ``rng``. 139 ``skcipher`` or ``rng``.
140 140
141 - *name* is the algorithm name and operation mode as string, e.g. 141 - *name* is the algorithm name and operation mode as string, e.g.
142 ``gcm(aes)``, ``pkcs1pad(rsa,sha256)``, ``sha256``, ``hmac(sha256)``, 142 ``sha256``, ``hmac(sha256)``, ``cbc(aes)`` or ``drbg_nopr_ctr_aes256``.
143 ``cbc(aes)`` or ``drbg_nopr_ctr_aes256``. 143
haypo 2016/08/29 00:11:35 Are all these algorithms always available on all p
christian.heimes 2016/08/29 08:10:37 It depends on the Kernel version which algorithms
144 144 - *feat* and *mask* are unsigned 32bit integers.
145 - *feat* and *mask* are unsigned int32 values. 145
haypo 2016/08/29 00:11:35 unsigned 32 bit integer values? For me, "int32" i
christian.heimes 2016/08/29 08:10:37 sounds good
146 Availability Linux 2.6.38, some algorithm types require more recent Kernels.
146 147
147 .. versionadded:: 3.6 148 .. versionadded:: 3.6
148 149
149 - Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`) 150 - Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`)
150 support specific representations. 151 support specific representations.
151 152
152 .. XXX document them! 153 .. XXX document them!
153 154
154 For IPv4 addresses, two special forms are accepted instead of a host address: 155 For IPv4 addresses, two special forms are accepted instead of a host address:
155 the empty string represents :const:`INADDR_ANY`, and the string 156 the empty string represents :const:`INADDR_ANY`, and the string
(...skipping 184 matching lines...) Expand 10 before | Expand all | Expand 10 after
340 SOL_RDS 341 SOL_RDS
341 RDS_* 342 RDS_*
342 343
343 Many constants of these forms, documented in the Linux documentation, are 344 Many constants of these forms, documented in the Linux documentation, are
344 also defined in the socket module. 345 also defined in the socket module.
345 346
346 Availability: Linux >= 2.6.30. 347 Availability: Linux >= 2.6.30.
347 348
348 .. versionadded:: 3.3 349 .. versionadded:: 3.3
349 350
351
350 .. data:: SIO_RCVALL 352 .. data:: SIO_RCVALL
351 SIO_KEEPALIVE_VALS 353 SIO_KEEPALIVE_VALS
352 SIO_LOOPBACK_FAST_PATH 354 SIO_LOOPBACK_FAST_PATH
353 RCVALL_* 355 RCVALL_*
354 356
355 Constants for Windows' WSAIoctl(). The constants are used as arguments to the 357 Constants for Windows' WSAIoctl(). The constants are used as arguments to the
356 :meth:`~socket.socket.ioctl` method of socket objects. 358 :meth:`~socket.socket.ioctl` method of socket objects.
357 359
358 .. versionchanged:: 3.6 360 .. versionchanged:: 3.6
359 ``SIO_LOOPBACK_FAST_PATH`` was added. 361 ``SIO_LOOPBACK_FAST_PATH`` was added.
360 362
361 363
362 .. data:: TIPC_* 364 .. data:: TIPC_*
363 365
364 TIPC related constants, matching the ones exported by the C socket API. See 366 TIPC related constants, matching the ones exported by the C socket API. See
365 the TIPC documentation for more information. 367 the TIPC documentation for more information.
366 368
367 .. data:: AF_ALG 369 .. data:: AF_ALG
368 SO_ALG 370 SOL_ALG
369 ALG_* 371 ALG_*
370 RDS_*
371 372
372 Constants for Linux Kernel cryptography. 373 Constants for Linux Kernel cryptography.
373 374
374 Availability: Linux >= 2.6.38. 375 Availability: Linux >= 2.6.38.
375 376
376 .. versionadded:: 3.6 377 .. versionadded:: 3.6
377 378
378 .. data:: AF_LINK 379 .. data:: AF_LINK
379 380
380 Availability: BSD, OSX. 381 Availability: BSD, OSX.
(...skipping 932 matching lines...) Expand 10 before | Expand all | Expand 10 after
1313 1314
1314 .. versionadded:: 3.3 1315 .. versionadded:: 3.3
1315 1316
1316 .. versionchanged:: 3.5 1317 .. versionchanged:: 3.5
1317 If the system call is interrupted and the signal handler does not raise 1318 If the system call is interrupted and the signal handler does not raise
1318 an exception, the method now retries the system call instead of raising 1319 an exception, the method now retries the system call instead of raising
1319 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). 1320 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale).
1320 1321
1321 .. method:: socket.sendmsg_afalg([msg], *, op[, iv[, assoclen[, flags]]]) 1322 .. method:: socket.sendmsg_afalg([msg], *, op[, iv[, assoclen[, flags]]])
1322 1323
1323 Specialized version of :meth:`~socket.sendmsg` for :const:`AF_ALG` socket. 1324 Specialized version of :meth:`~socket.sendmsg` for :const:`AF_ALG` socket.
haypo 2016/08/29 00:11:35 Is it possible to implement sendmsg_afalg() in pur
christian.heimes 2016/08/29 08:10:37 It is possible to implement this with sendmsg(). I
1324 Set mode, IV, AEAD associated data length and flags for :const:`AF_ALG` socke t. 1325 Set mode, IV, AEAD associated data length and flags for :const:`AF_ALG` socke t.
1325 1326
1326 Availability: Linux >= 2.6.38 1327 Availability: Linux >= 2.6.38
1327 1328
1328 .. versionadded:: 3.6 1329 .. versionadded:: 3.6
1329 1330
1330 .. method:: socket.sendfile(file, offset=0, count=None) 1331 .. method:: socket.sendfile(file, offset=0, count=None)
1331 1332
1332 Send a file until EOF is reached by using high-performance 1333 Send a file until EOF is reached by using high-performance
1333 :mod:`os.sendfile` and return the total number of bytes which were sent. 1334 :mod:`os.sendfile` and return the total number of bytes which were sent.
(...skipping 34 matching lines...) Expand 10 before | Expand all | Expand 10 after
1368 Set a timeout on blocking socket operations. The *value* argument can be a 1369 Set a timeout on blocking socket operations. The *value* argument can be a
1369 nonnegative floating point number expressing seconds, or ``None``. 1370 nonnegative floating point number expressing seconds, or ``None``.
1370 If a non-zero value is given, subsequent socket operations will raise a 1371 If a non-zero value is given, subsequent socket operations will raise a
1371 :exc:`timeout` exception if the timeout period *value* has elapsed before 1372 :exc:`timeout` exception if the timeout period *value* has elapsed before
1372 the operation has completed. If zero is given, the socket is put in 1373 the operation has completed. If zero is given, the socket is put in
1373 non-blocking mode. If ``None`` is given, the socket is put in blocking mode. 1374 non-blocking mode. If ``None`` is given, the socket is put in blocking mode.
1374 1375
1375 For further information, please consult the :ref:`notes on socket timeouts <s ocket-timeouts>`. 1376 For further information, please consult the :ref:`notes on socket timeouts <s ocket-timeouts>`.
1376 1377
1377 1378
1378 .. method:: socket.setsockopt(level, optname, value[, intvalue]) 1379 .. method:: socket.setsockopt(level, optname, value: int)
haypo 2016/08/28 23:53:21 Ditto: I suggest to document the 3 syntaxes: .. m
christian.heimes 2016/08/29 08:10:37 I like that :)
1380 .. method:: socket.setsockopt(level, optname, value: buffer)
1381 .. method:: socket.setsockopt(level, optname, None, optlen: int)
1379 1382
1380 .. index:: module: struct 1383 .. index:: module: struct
1381 1384
1382 Set the value of the given socket option (see the Unix manual page 1385 Set the value of the given socket option (see the Unix manual page
1383 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the 1386 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the
1384 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer, 1387 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer,
1385 None or or a :term:`bytes-like object` representing a buffer. In the later 1388 None or or a :term:`bytes-like object` representing a buffer. In the later
Martin Panter 2016/09/04 16:01:03 “or” is doubled
christian.heimes 2016/09/04 16:58:44 thanks, fixed
1386 case it is up to the caller to ensure that the bytestring contains the 1389 case it is up to the caller to ensure that the bytestring contains the
1387 proper bits (see the optional built-in module :mod:`struct` for a way to 1390 proper bits (see the optional built-in module :mod:`struct` for a way to
1388 encode C structures as bytestrings). When value is set to None, 1391 encode C structures as bytestrings). When value is set to None,
1389 intvalue argument is required. It's equivalent to call setsockopt C 1392 optlen argument is required. It's equivalent to call setsockopt C
1390 function with optval=NULL and optlen=intvalue. 1393 function with optval=NULL and optlen=optlen.
1391 1394
1392 1395
1393 .. versionchanged:: 3.5 1396 .. versionchanged:: 3.5
1394 Writable :term:`bytes-like object` is now accepted. 1397 Writable :term:`bytes-like object` is now accepted.
1395 1398
1396 .. versionchanged:: 3.6 1399 .. versionchanged:: 3.6
1397 None, intvalue form added 1400 setsockopt(level, optname, None, optlen: int) form added.
haypo 2016/08/28 23:53:21 setsockopt(level, optname, None, length: int) form
1398 1401
1399 1402
1400 .. method:: socket.shutdown(how) 1403 .. method:: socket.shutdown(how)
1401 1404
1402 Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD` , 1405 Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD` ,
1403 further receives are disallowed. If *how* is :const:`SHUT_WR`, further sends 1406 further receives are disallowed. If *how* is :const:`SHUT_WR`, further sends
1404 are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives a re 1407 are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives a re
1405 disallowed. 1408 disallowed.
1406 1409
1407 1410
(...skipping 309 matching lines...) Expand 10 before | Expand all | Expand 10 after
1717 1720
1718 - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Lef fler et 1721 - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Lef fler et
1719 al, 1722 al,
1720 1723
1721 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections 1724 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections
1722 PS1:7 and PS1:8). The platform-specific reference material for the various 1725 PS1:7 and PS1:8). The platform-specific reference material for the various
1723 socket-related system calls are also a valuable source of information on the 1726 socket-related system calls are also a valuable source of information on the
1724 details of socket semantics. For Unix, refer to the manual pages; for Window s, 1727 details of socket semantics. For Unix, refer to the manual pages; for Window s,
1725 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers m ay 1728 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers m ay
1726 want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv 6. 1729 want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv 6.
LEFTRIGHT

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+