Prepare crypto framework for IPsec ESN support

This permits requests (netipsec ESP and AH protocol) to provide the
IPsec ESN (Extended Sequence Numbers) in a separate buffer.

As with separate output buffer and separate AAD buffer not all drivers
support this feature. Consumer must request use of this feature via new
session flag.

Submitted by:           Grzegorz Jaszczyk <jaz@semihalf.com>
                        Patryk Duda <pdk@semihalf.com>
Reviewed by:            jhb
Differential revision:  https://reviews.freebsd.org/D24838
Obtained from:          Semihalf
Sponsored by:           Stormshield

2 files changed, 27 insertions, 0 deletions

diff --git a/share/man/man9/crypto_request.9 b/share/man/man9/crypto_request.9
index 8ba075b06cf0c..6253e49dfb325 100644
--- a/share/man/man9/crypto_request.9
+++ b/share/man/man9/crypto_request.9
@@ -302,6 +302,24 @@ as a single buffer pointed to by
 In either case,
 .Fa crp_aad_length
 always indicates the amount of AAD in bytes.
+.Ss Request ESN
+IPsec requests may optionally include Extended Sequence Numbers (ESN).
+ESN may either be supplied in
+.Fa crp_esn
+or as part of the AAD pointed to by
+.Fa crp_aad .
+.Pp
+If the ESN is stored in
+.Fa crp_esn ,
+.Dv CSP_F_ESN
+should be set in
+.Fa csp_flags .
+This use case is dedicated for encrypt and authenticate mode, since the
+high-order 32 bits of the sequence number are appended after the Next Header
+(RFC 4303).
+.Pp
+AEAD modes supply the ESN in a separate AAD buffer (see e.g. RFC 4106, Chapter 5
+AAD Construction).
 .Ss Request IV and/or Nonce
 Some cryptographic operations require an IV or nonce as an input.
 An IV may be stored either in the IV region of the data buffer or in
diff --git a/share/man/man9/crypto_session.9 b/share/man/man9/crypto_session.9
index c370039a51d1e..78bc5e736655d 100644
--- a/share/man/man9/crypto_session.9
+++ b/share/man/man9/crypto_session.9
@@ -201,6 +201,15 @@ Sessions with this flag set permit requests with AAD passed in either in
 a region of the input buffer or in a single, virtually-contiguous buffer.
 Sessions without this flag only permit requests with AAD passed in as
 a region in the input buffer.
+.It Dv CSP_F_ESN
+Support requests that use a separate buffer for IPsec ESN (Extended Sequence
+Numbers).
+.Pp
+Sessions with this flag set permit requests with IPsec ESN passed in special
+buffer.
+It is required for IPsec ESN support of encrypt and authenticate mode where
+the high-order 32 bits of the sequence number are appended after the Next
+Header (RFC 4303).
 .El
 .It Fa csp_ivlen
 If either the cipher or authentication algorithms require an explicit