From 98f56be49a162ad42edffaa681c381941909e325 Mon Sep 17 00:00:00 2001
From: okir <okir@c6295689-39f2-0310-b995-f0e70906c6a9>
Date: Thu, 17 Jul 2003 23:03:16 +0000
Subject: [PATCH] - added sc_pkcs15_compute_signature.3 draft

git-svn-id: https://www.opensc-project.org/svnp/opensc/trunk@1282 c6295689-39f2-0310-b995-f0e70906c6a9
---
 docs/Makefile.am                   |  3 +-
 docs/sc_pkcs15_compute_signature.3 | 87 ++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+), 1 deletion(-)
 create mode 100644 docs/sc_pkcs15_compute_signature.3

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 1526ae13..a21eda8e 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -27,7 +27,8 @@ MANSRC  	= pkcs15-crypt.1 \
 		  sc_read_binary.3 \
 		  sc_read_record.3 \
 		  sc_release_context.3 \
-		  sc_select_file.3
+		  sc_select_file.3 \
+		  sc_pkcs15_compute_signature.3
 man_MANS	= $(MANSRC) pkcs15-profile.5
 noinst_DATA	= $(HTMLFILES)
 EXTRA_DIST	= $(MANSRC) pkcs15-profile.5.in pkcs-15v1_1.asn \
diff --git a/docs/sc_pkcs15_compute_signature.3 b/docs/sc_pkcs15_compute_signature.3
new file mode 100644
index 00000000..328344fd
--- /dev/null
+++ b/docs/sc_pkcs15_compute_signature.3
@@ -0,0 +1,87 @@
+.TH sc_pkcs15_compute_signature 3 "July 2003" "OpenSC Programmer's Manual
+.SH NAME
+sc_pkcs15_compute_signature \- compute digitial signature
+.SH SYNOPSIS
+.nf
+.B #include <opensc.h>
+.sp
+.BI "int sc_pkcs15_compute_signature(struct sc_pkcs15_card *p15card,
+.BI "                   const struct sc_pkcs15_object *obj,
+.BI "                   unsigned long flags, const u8 *in, size_t inlen,
+.BI "                   u8 *out, size_t outlen);
+.fi
+.SH DESCRIPTION
+This function digitally signs the data pointed to by
+.BR in ,
+using the key identified by
+.BR obj , 
+and places the resulting signature in the buffer pointed to by
+.BR out .
+The signature operation will be performed on the smart card
+identified by
+.BR p15card .
+.PP
+Currently, only RSA signatures are supported.
+.PP
+The
+.B flags
+argument provides additional information on how the signature is
+to be computed. In particular, it specifies how the input data
+should be padded:
+.TP
+.B SC_ALGORITHM_RSA_RAW
+requests that the card should sign the provided data as-is.
+The length of the input data must match the modulus length
+of the key.
+.TP
+.B SC_ALGORITHM_RSA_PAD_PKCS1
+requests that the card should sign the provided data,
+padding it according to the padding algorithm specified
+in PKCS#1.
+.IP
+The input data must be the output of a digest (hash) function.
+As PKCS#1 padding includes an identifier of the hash algorithm
+used, the
+.B flags
+argument must indicate the hash algorithm used,
+by ORing
+.B SC_ALGORITHM_RSA_PAD_PKCS1
+with one of the following values:
+.BR SC_ALGORITHM_RSA_HASH_MD5 ,
+.BR SC_ALGORITHM_RSA_HASH_SHA1 ,
+.BR SC_ALGORITHM_RSA_HASH_RIPEMD160 ", or
+.BR SC_ALGORITHM_RSA_HASH_MD5_SHA1 .
+.IP
+In any of these cases, the length of the input data must match
+the digest length of the hash algorithm.
+.TP
+.B SC_ALGORITHM_RSA_PAD_ANSI
+requests that the card should use ANSI padding when signing the
+provided data.
+.TP
+.B SC_ALGORITHM_RSA_PAD_ISO9796
+requests that the card should use ISO 9796 padding when signing the
+provided data.
+.\"
+.\"
+.\"
+.SH Card Driver Considerations
+Depending on the card's capabilities,
+.B sc_pkcs15_compute_signature
+is able to process the provided data so that it is in a form
+suitable for the card. For instance, if a smart card supports
+raw RSA only, the function will have to add the required
+padding before passing it to the card driver.
+Conversely, an error should be returned if the card supports
+only PKCS#1 padding with a specific set of hash algorithms.
+.PP
+...
+.SH RETURN VALUE
+If an error occurred, a negative error code is returned, as described
+in \fbsc_error\fP(3). Otherwise, the function will return the
+size of the signature.
+.SH SEE ALSO
+.BR sc_pkcs15_decipher (3),
+.BR sc_compute_signature (3).
+.SH AUTHOR
+This manual page was written by Olaf Kirch <okir@suse.de>