Merge tag 'tegra-for-5.5-soc-fixes' of git://git.kernel.org/pub/scm/linux/kernel...

[linux.git] / include / crypto / akcipher.h

diff --git a/include/crypto/akcipher.h b/include/crypto/akcipher.h
index 2d690494568cf8b4e70fcc93a5d324d286cf6616..6924b091adec18400ac84b3d9a36bc54c4052f9a 100644 (file)
--- a/include/crypto/akcipher.h
+++ b/include/crypto/akcipher.h
@@ -1,14 +1,9 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
 /*
  * Public Key Encryption
  *
  * Copyright (c) 2015, Intel Corporation
  * Authors: Tadeusz Struk <tadeusz.struk@intel.com>
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms of the GNU General Public License as published by the Free
- * Software Foundation; either version 2 of the License, or (at your option)
- * any later version.
- *
  */
 #ifndef _CRYPTO_AKCIPHER_H
 #define _CRYPTO_AKCIPHER_H
@@ -19,14 +14,20 @@
  *
  * @base:      Common attributes for async crypto requests
  * @src:       Source data
- * @dst:       Destination data
+ *             For verify op this is signature + digest, in that case
+ *             total size of @src is @src_len + @dst_len.
+ * @dst:       Destination data (Should be NULL for verify op)
  * @src_len:   Size of the input buffer
- * @dst_len:   Size of the output buffer. It needs to be at least
- *             as big as the expected result depending on the operation
+ *             For verify op it's size of signature part of @src, this part
+ *             is supposed to be operated by cipher.
+ * @dst_len:   Size of @dst buffer (for all ops except verify).
+ *             It needs to be at least as big as the expected result
+ *             depending on the operation.
  *             After operation it will be updated with the actual size of the
  *             result.
  *             In case of error where the dst sgl size was insufficient,
  *             it will be updated to the size required for the operation.
+ *             For verify op this is size of digest part in @src.
  * @__ctx:     Start of private context data
  */
 struct akcipher_request {
@@ -55,10 +56,9 @@ struct crypto_akcipher {
  *             algorithm. In case of error, where the dst_len was insufficient,
  *             the req->dst_len will be updated to the size required for the
  *             operation
- * @verify:    Function performs a sign operation as defined by public key
- *             algorithm. In case of error, where the dst_len was insufficient,
- *             the req->dst_len will be updated to the size required for the
- *             operation
+ * @verify:    Function performs a complete verify operation as defined by
+ *             public key algorithm, returning verification status. Requires
+ *             digest value as input parameter.
  * @encrypt:   Function performs an encrypt operation as defined by public key
  *             algorithm. In case of error, where the dst_len was insufficient,
  *             the req->dst_len will be updated to the size required for the
@@ -69,10 +69,10 @@ struct crypto_akcipher {
  *             operation
  * @set_pub_key: Function invokes the algorithm specific set public key
  *             function, which knows how to decode and interpret
- *             the BER encoded public key
+ *             the BER encoded public key and parameters
  * @set_priv_key: Function invokes the algorithm specific set private key
  *             function, which knows how to decode and interpret
- *             the BER encoded private key
+ *             the BER encoded private key and parameters
  * @max_size:  Function returns dest buffer size required for a given key.
  * @init:      Initialize the cryptographic transformation object.
  *             This function is used to initialize the cryptographic
@@ -238,9 +238,10 @@ static inline void akcipher_request_set_callback(struct akcipher_request *req,
  *
  * @req:       public key request
  * @src:       ptr to input scatter list
- * @dst:       ptr to output scatter list
+ * @dst:       ptr to output scatter list or NULL for verify op
  * @src_len:   size of the src input scatter list to be processed
- * @dst_len:   size of the dst output scatter list
+ * @dst_len:   size of the dst output scatter list or size of signature
+ *             portion in @src for verify op
  */
 static inline void akcipher_request_set_crypt(struct akcipher_request *req,
                                              struct scatterlist *src,
@@ -343,14 +344,18 @@ static inline int crypto_akcipher_sign(struct akcipher_request *req)
 }
 
 /**
- * crypto_akcipher_verify() - Invoke public key verify operation
+ * crypto_akcipher_verify() - Invoke public key signature verification
  *
- * Function invokes the specific public key verify operation for a given
- * public key algorithm
+ * Function invokes the specific public key signature verification operation
+ * for a given public key algorithm.
  *
  * @req:       asymmetric key request
  *
- * Return: zero on success; error code in case of error
+ * Note: req->dst should be NULL, req->src should point to SG of size
+ * (req->src_size + req->dst_size), containing signature (of req->src_size
+ * length) with appended digest (of req->dst_size length).
+ *
+ * Return: zero on verification success; error code in case of error.
  */
 static inline int crypto_akcipher_verify(struct akcipher_request *req)
 {
@@ -369,11 +374,12 @@ static inline int crypto_akcipher_verify(struct akcipher_request *req)
  * crypto_akcipher_set_pub_key() - Invoke set public key operation
  *
  * Function invokes the algorithm specific set key function, which knows
- * how to decode and interpret the encoded key
+ * how to decode and interpret the encoded key and parameters
  *
  * @tfm:       tfm handle
- * @key:       BER encoded public key
- * @keylen:    length of the key
+ * @key:       BER encoded public key, algo OID, paramlen, BER encoded
+ *             parameters
+ * @keylen:    length of the key (not including other data)
  *
  * Return: zero on success; error code in case of error
  */
@@ -390,11 +396,12 @@ static inline int crypto_akcipher_set_pub_key(struct crypto_akcipher *tfm,
  * crypto_akcipher_set_priv_key() - Invoke set private key operation
  *
  * Function invokes the algorithm specific set key function, which knows
- * how to decode and interpret the encoded key
+ * how to decode and interpret the encoded key and parameters
  *
  * @tfm:       tfm handle
- * @key:       BER encoded private key
- * @keylen:    length of the key
+ * @key:       BER encoded private key, algo OID, paramlen, BER encoded
+ *             parameters
+ * @keylen:    length of the key (not including other data)
  *
  * Return: zero on success; error code in case of error
  */