.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 ,
.BR SC_ALGORITHM_RSA_HASH_MD5_SHA1 , or
.BR SC_ALGORITHM_RSA_HASH_NONE .
.IP
In any of these cases, the length of the input data must match
the digest length of the hash algorithm. In the first 3 cases,
the respective digestinfo is prepended to the input data (the
hash), in the last 2 cases, no digestinfo is prepended.
.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>