root
/
openssl
mirror of https://github.com/openssl/openssl.git
1
0
Fork 0
Code Issues Actions 7 Packages Projects Releases Wiki Activity
openssl/doc/man3/RSA_sign.pod

78 lines
2.3 KiB
Plaintext
Raw Normal View History

Document the RSA library.
2000-01-12 06:35:21 +08:00
=pod
=head1 NAME
RSA_sign, RSA_verify - RSA signatures
=head1 SYNOPSIS
#include <openssl/rsa.h>
Clarify the deprecation warnings in the docs There was recently an instance where a user was confused by the deprecation warnings in the docs. They believed the warning applied to the immediately preceding function declarations, when it fact it applied to the following function declarations. https://mta.openssl.org/pipermail/openssl-users/2021-December/014665.html We clarify the wording to make it clear that the warning applies to the following functions. Reviewed-by: Paul Dale <pauli@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/17180) (cherry picked from commit 3dbf82438004b31258627f324841476c4f586c19)
2021-12-02 19:33:49 +08:00
The following functions have been deprecated since OpenSSL 3.0, and can be
hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
see L<openssl_user_macros(7)>:
rsa: document deprecated low level functions Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11063)
2020-02-12 13:23:01 +08:00
the pointer to the message digest is const
2005-04-21 17:43:09 +08:00
int RSA_sign(int type, const unsigned char *m, unsigned int m_len,
doc/man3: reformat the function prototypes in the synopses I tried hard to keep the lines at 80 characters or less, but in a few cases I had to punt and just indented the subsequent lines by 4 spaces. A few well-placed typedefs for callback functions would really help, but these would be part of the API, so that's probably for later. I also took the liberty of inserting empty lines in overlong blocks to provide some visual space. Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1956)
2017-01-21 02:58:49 +08:00
unsigned char *sigret, unsigned int *siglen, RSA *rsa);
Document the RSA library.
2000-01-12 06:35:21 +08:00
the pointer to the message digest is const
2005-04-21 17:43:09 +08:00
int RSA_verify(int type, const unsigned char *m, unsigned int m_len,
doc/man3: reformat the function prototypes in the synopses I tried hard to keep the lines at 80 characters or less, but in a few cases I had to punt and just indented the subsequent lines by 4 spaces. A few well-placed typedefs for callback functions would really help, but these would be part of the API, so that's probably for later. I also took the liberty of inserting empty lines in overlong blocks to provide some visual space. Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1956)
2017-01-21 02:58:49 +08:00
unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
Document the RSA library.
2000-01-12 06:35:21 +08:00
=head1 DESCRIPTION
rsa: document deprecated low level functions Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11063)
2020-02-12 13:23:01 +08:00
All of the functions described on this page are deprecated.
Applications should instead use L<EVP_PKEY_sign_init(3)>, L<EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify_init(3)> and L<EVP_PKEY_verify(3)>.
Document the RSA library.
2000-01-12 06:35:21 +08:00
RSA_sign() signs the message digest B<m> of size B<m_len> using the
Make RSA_sign.pod less confusing. PKCS #1 v2.0 is the name of a document which specifies an algorithm RSASSA-PKCS1-v1_5, often referred to as "PKCS #1 v1.5" after an earlier document which specified it. This gets further confusing because the document PKCS #1 v2.1 specifies two signature algorithms, RSASSA-PKCS1-v1_5 and RSASSA-PSS. RSA_sign implements RSASSA-PKCS1-v1_5. Refer to the document using the RFC number which is easier to find anyway, and refer to the algorithm by its name. Reviewed-by: Kurt Roeckx <kurt@roeckx.be> Reviewed-by: Rich Salz <rsalz@openssl.org> GH: #1474
2016-08-21 03:48:56 +08:00
private key B<rsa> using RSASSA-PKCS1-v1_5 as specified in RFC 3447. It
stores the signature in B<sigret> and the signature size in B<siglen>.
B<sigret> must point to RSA_size(B<rsa>) bytes of memory.
Close a whole bunch of documentation-related tickets: 298 424 656 882 939 1630 1807 2263 2294 2311 2424 2623 2637 2686 2697 2921 2922 2940 3055 3112 3156 3177 3277
2014-07-03 10:42:40 +08:00
Note that PKCS #1 adds meta-data, placing limits on the size of the
key that can be used.
Fix L<> content in manpages L<foo|foo> is sub-optimal If the xref is the same as the title, which is what we do, then you only need L<foo>. This fixes all 1457 occurrences in 349 files. Approximately. (And pod used to need both.) Reviewed-by: Richard Levitte <levitte@openssl.org>
2015-08-18 03:21:33 +08:00
See L<RSA_private_encrypt(3)> for lower-level
Close a whole bunch of documentation-related tickets: 298 424 656 882 939 1630 1807 2263 2294 2311 2424 2623 2637 2686 2697 2921 2922 2940 3055 3112 3156 3177 3277
2014-07-03 10:42:40 +08:00
operations.
Document the RSA library.
2000-01-12 06:35:21 +08:00
B<type> denotes the message digest algorithm that was used to generate
Various doc fixes. Make all mention of digest algorithm use "any supported algorithm" RT2071, some new manpages from Victor B. Wagner <vitus@cryptocom.ru>: X509_LOOKUP_hash_dir.pod X509_check_ca.pod X509_check_issued.pod RT 1600: Remove references to non-existant objects(3) Add RETURN VALUES to BIO_do_accept page. RT1818: RSA_sign Can return values other than 0 on failure. RT3634: Fix AES CBC aliases (Steffen Nurpmeso <sdaoden@yandex.com>) RT3678: Some clarifications to BIO_new_pair (Devchandra L Meetei <dlmeetei@gmail.com>) RT3787: Fix some EVP_ function return values (Laetitia Baudoin <lbaudoin@google.com>) Reviewed-by: Tim Hudson <tjh@openssl.org>
2015-08-28 00:28:08 +08:00
B<m>.
If B<type> is B<NID_md5_sha1>,
Document the RSA library.
2000-01-12 06:35:21 +08:00
an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding
and no algorithm identifier) is created.
RSA_verify() verifies that the signature B<sigbuf> of size B<siglen>
matches a given message digest B<m> of size B<m_len>. B<type> denotes
the message digest algorithm that was used to generate the signature.
B<rsa> is the signer's public key.
=head1 RETURN VALUES
Various doc fixes. Make all mention of digest algorithm use "any supported algorithm" RT2071, some new manpages from Victor B. Wagner <vitus@cryptocom.ru>: X509_LOOKUP_hash_dir.pod X509_check_ca.pod X509_check_issued.pod RT 1600: Remove references to non-existant objects(3) Add RETURN VALUES to BIO_do_accept page. RT1818: RSA_sign Can return values other than 0 on failure. RT3634: Fix AES CBC aliases (Steffen Nurpmeso <sdaoden@yandex.com>) RT3678: Some clarifications to BIO_new_pair (Devchandra L Meetei <dlmeetei@gmail.com>) RT3787: Fix some EVP_ function return values (Laetitia Baudoin <lbaudoin@google.com>) Reviewed-by: Tim Hudson <tjh@openssl.org>
2015-08-28 00:28:08 +08:00
RSA_sign() returns 1 on success.
RSA_verify() returns 1 on successful verification.
Document the RSA library.
2000-01-12 06:35:21 +08:00
Fix L<> content in manpages L<foo|foo> is sub-optimal If the xref is the same as the title, which is what we do, then you only need L<foo>. This fixes all 1457 occurrences in 349 files. Approximately. (And pod used to need both.) Reviewed-by: Richard Levitte <levitte@openssl.org>
2015-08-18 03:21:33 +08:00
The error codes can be obtained by L<ERR_get_error(3)>.
Document the RSA library.
2000-01-12 06:35:21 +08:00
=head1 CONFORMING TO
SSL, PKCS #1 v2.0
=head1 SEE ALSO
Various doc fixes. Make all mention of digest algorithm use "any supported algorithm" RT2071, some new manpages from Victor B. Wagner <vitus@cryptocom.ru>: X509_LOOKUP_hash_dir.pod X509_check_ca.pod X509_check_issued.pod RT 1600: Remove references to non-existant objects(3) Add RETURN VALUES to BIO_do_accept page. RT1818: RSA_sign Can return values other than 0 on failure. RT3634: Fix AES CBC aliases (Steffen Nurpmeso <sdaoden@yandex.com>) RT3678: Some clarifications to BIO_new_pair (Devchandra L Meetei <dlmeetei@gmail.com>) RT3787: Fix some EVP_ function return values (Laetitia Baudoin <lbaudoin@google.com>) Reviewed-by: Tim Hudson <tjh@openssl.org>
2015-08-28 00:28:08 +08:00
L<ERR_get_error(3)>,
Clean up "generic" intro pod files. Files like dh.pod, etc., mostly duplicated the API-specific pod files. Removed the duplicated content; that often mean the whole file could be removed. Some of the content about internals got moved into README files in the source tree. Some content (e.g., err.pod) got moved into other pod pages. Annotate generic pages, remove dup NAME Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-06-10 04:39:19 +08:00
L<RSA_private_encrypt(3)>,
Fix nits in pod files. Add doc-nit-check to help find future issues. Make podchecker be almost clean. Remove trailing whitespace. Tab expansion Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-20 20:11:46 +08:00
L<RSA_public_decrypt(3)>
Document the RSA library.
2000-01-12 06:35:21 +08:00
rsa: document deprecated low level functions Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11063)
2020-02-12 13:23:01 +08:00
=head1 HISTORY
All of these functions were deprecated in OpenSSL 3.0.
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
=head1 COPYRIGHT
Update copyright year Reviewed-by: Richard Levitte <levitte@openssl.org>
2021-12-14 22:41:27 +08:00
Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
Following the license change, modify the boilerplates in doc/man3/ [skip ci] Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/7829)
2018-12-06 21:04:44 +08:00
Licensed under the Apache License 2.0 (the "License"). You may not use
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut