From 195fe5e91c60bd205043b4bea113abdff1c67bcc Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Fri, 4 Nov 2016 10:17:17 +0000 Subject: convert RSA manuals from pod to mdoc --- src/lib/libcrypto/doc/RSA_blinding_on.pod | 41 --- src/lib/libcrypto/doc/RSA_check_key.pod | 67 ---- src/lib/libcrypto/doc/RSA_generate_key.pod | 79 ----- src/lib/libcrypto/doc/RSA_get_ex_new_index.pod | 122 -------- src/lib/libcrypto/doc/RSA_new.pod | 39 --- .../libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod | 121 -------- src/lib/libcrypto/doc/RSA_print.pod | 49 --- src/lib/libcrypto/doc/RSA_private_encrypt.pod | 69 ----- src/lib/libcrypto/doc/RSA_public_encrypt.pod | 82 ----- src/lib/libcrypto/doc/RSA_set_method.pod | 201 ------------ src/lib/libcrypto/doc/RSA_sign.pod | 61 ---- .../libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod | 57 ---- src/lib/libcrypto/doc/RSA_size.pod | 33 -- src/lib/libcrypto/doc/d2i_RSAPublicKey.pod | 63 ---- src/lib/libcrypto/doc/rsa.pod | 123 -------- src/lib/libcrypto/man/Makefile | 32 +- src/lib/libcrypto/man/RSA_blinding_on.3 | 46 +++ src/lib/libcrypto/man/RSA_check_key.3 | 97 ++++++ src/lib/libcrypto/man/RSA_generate_key.3 | 105 +++++++ src/lib/libcrypto/man/RSA_get_ex_new_index.3 | 227 ++++++++++++++ src/lib/libcrypto/man/RSA_new.3 | 46 +++ .../libcrypto/man/RSA_padding_add_PKCS1_type_1.3 | 197 ++++++++++++ src/lib/libcrypto/man/RSA_print.3 | 91 ++++++ src/lib/libcrypto/man/RSA_private_encrypt.3 | 97 ++++++ src/lib/libcrypto/man/RSA_public_encrypt.3 | 108 +++++++ src/lib/libcrypto/man/RSA_set_method.3 | 339 +++++++++++++++++++++ src/lib/libcrypto/man/RSA_sign.3 | 103 +++++++ src/lib/libcrypto/man/RSA_sign_ASN1_OCTET_STRING.3 | 81 +++++ src/lib/libcrypto/man/RSA_size.3 | 27 ++ src/lib/libcrypto/man/d2i_RSAPublicKey.3 | 101 ++++++ src/lib/libcrypto/man/rsa.3 | 238 +++++++++++++++ 31 files changed, 1919 insertions(+), 1223 deletions(-) delete mode 100644 src/lib/libcrypto/doc/RSA_blinding_on.pod delete mode 100644 src/lib/libcrypto/doc/RSA_check_key.pod delete mode 100644 src/lib/libcrypto/doc/RSA_generate_key.pod delete mode 100644 src/lib/libcrypto/doc/RSA_get_ex_new_index.pod delete mode 100644 src/lib/libcrypto/doc/RSA_new.pod delete mode 100644 src/lib/libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod delete mode 100644 src/lib/libcrypto/doc/RSA_print.pod delete mode 100644 src/lib/libcrypto/doc/RSA_private_encrypt.pod delete mode 100644 src/lib/libcrypto/doc/RSA_public_encrypt.pod delete mode 100644 src/lib/libcrypto/doc/RSA_set_method.pod delete mode 100644 src/lib/libcrypto/doc/RSA_sign.pod delete mode 100644 src/lib/libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod delete mode 100644 src/lib/libcrypto/doc/RSA_size.pod delete mode 100644 src/lib/libcrypto/doc/d2i_RSAPublicKey.pod delete mode 100644 src/lib/libcrypto/doc/rsa.pod create mode 100644 src/lib/libcrypto/man/RSA_blinding_on.3 create mode 100644 src/lib/libcrypto/man/RSA_check_key.3 create mode 100644 src/lib/libcrypto/man/RSA_generate_key.3 create mode 100644 src/lib/libcrypto/man/RSA_get_ex_new_index.3 create mode 100644 src/lib/libcrypto/man/RSA_new.3 create mode 100644 src/lib/libcrypto/man/RSA_padding_add_PKCS1_type_1.3 create mode 100644 src/lib/libcrypto/man/RSA_print.3 create mode 100644 src/lib/libcrypto/man/RSA_private_encrypt.3 create mode 100644 src/lib/libcrypto/man/RSA_public_encrypt.3 create mode 100644 src/lib/libcrypto/man/RSA_set_method.3 create mode 100644 src/lib/libcrypto/man/RSA_sign.3 create mode 100644 src/lib/libcrypto/man/RSA_sign_ASN1_OCTET_STRING.3 create mode 100644 src/lib/libcrypto/man/RSA_size.3 create mode 100644 src/lib/libcrypto/man/d2i_RSAPublicKey.3 create mode 100644 src/lib/libcrypto/man/rsa.3 (limited to 'src/lib') diff --git a/src/lib/libcrypto/doc/RSA_blinding_on.pod b/src/lib/libcrypto/doc/RSA_blinding_on.pod deleted file mode 100644 index f96e3cf7c9..0000000000 --- a/src/lib/libcrypto/doc/RSA_blinding_on.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -RSA_blinding_on, RSA_blinding_off - protect the RSA operation from timing -attacks - -=head1 SYNOPSIS - - #include - - int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); - - void RSA_blinding_off(RSA *rsa); - -=head1 DESCRIPTION - -RSA is vulnerable to timing attacks. In a setup where attackers can -measure the time of RSA decryption or signature operations, blinding -must be used to protect the RSA operation from that attack. - -RSA_blinding_on() turns blinding on for key B and generates a -random blinding factor. B is B or a pre-allocated and -initialized B. - -RSA_blinding_off() turns blinding off and frees the memory used for -the blinding factor. - -=head1 RETURN VALUES - -RSA_blinding_on() returns 1 on success, and 0 if an error occurred. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -RSA_blinding_on() and RSA_blinding_off() appeared in SSLeay 0.9.0. - -=cut diff --git a/src/lib/libcrypto/doc/RSA_check_key.pod b/src/lib/libcrypto/doc/RSA_check_key.pod deleted file mode 100644 index a5198f3db5..0000000000 --- a/src/lib/libcrypto/doc/RSA_check_key.pod +++ /dev/null @@ -1,67 +0,0 @@ -=pod - -=head1 NAME - -RSA_check_key - validate private RSA keys - -=head1 SYNOPSIS - - #include - - int RSA_check_key(RSA *rsa); - -=head1 DESCRIPTION - -This function validates RSA keys. It checks that B

and B are -in fact prime, and that B. - -It also checks that B, -and that B, B and B are set correctly or are B. - -As such, this function can not be used with any arbitrary RSA key object, -even if it is otherwise fit for regular RSA operation. See B for more -information. - -=head1 RETURN VALUE - -RSA_check_key() returns 1 if B is a valid RSA key, and 0 otherwise. --1 is returned if an error occurs while checking the key. - -If the key is invalid or an error occurred, the reason code can be -obtained using L. - -=head1 NOTES - -This function does not work on RSA public keys that have only the modulus -and public exponent elements populated. It performs integrity checks on all -the RSA key material, so the RSA key structure must contain all the private -key data too. - -Unlike most other RSA functions, this function does B work -transparently with any underlying ENGINE implementation because it uses the -key data in the RSA structure directly. An ENGINE implementation can -override the way key data is stored and handled, and can even provide -support for HSM keys - in which case the RSA structure may contain B -key data at all! If the ENGINE in question is only being used for -acceleration or analysis purposes, then in all likelihood the RSA key data -is complete and untouched, but this can't be assumed in the general case. - -=head1 BUGS - -A method of verifying the RSA key using opaque RSA API functions might need -to be considered. Right now RSA_check_key() simply uses the RSA structure -elements directly, bypassing the RSA_METHOD table altogether (and -completely violating encapsulation and object-orientation in the process). -The best fix will probably be to introduce a "check_key()" handler to the -RSA_METHOD function table so that alternative implementations can also -provide their own verifiers. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -RSA_check_key() appeared in OpenSSL 0.9.4. - -=cut diff --git a/src/lib/libcrypto/doc/RSA_generate_key.pod b/src/lib/libcrypto/doc/RSA_generate_key.pod deleted file mode 100644 index 00026f04df..0000000000 --- a/src/lib/libcrypto/doc/RSA_generate_key.pod +++ /dev/null @@ -1,79 +0,0 @@ -=pod - -=head1 NAME - -RSA_generate_key_ex, RSA_generate_key - generate RSA key pair - -=head1 SYNOPSIS - - #include - - int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); - -Deprecated: - - RSA *RSA_generate_key(int num, unsigned long e, - void (*callback)(int,int,void *), void *cb_arg); - -=head1 DESCRIPTION - -RSA_generate_key_ex() generates a key pair and stores it in the B -structure provided in B. - -The modulus size will be of length B, and the public exponent will be -B. Key sizes with B E 1024 should be considered insecure. -The exponent is an odd number, typically 3, 17 or 65537. - -A callback function may be used to provide feedback about the -progress of the key generation. If B is not B, it -will be called as follows using the BN_GENCB_call() function -described on the L page: - -=over 4 - -=item * - -While a random prime number is generated, it is called as -described in L. - -=item * - -When the n-th randomly generated prime is rejected as not -suitable for the key, B is called. - -=item * - -When a random p has been found with p-1 relatively prime to B, -it is called as B. - -=back - -The process is then repeated for prime q with B. - -RSA_generate_key is deprecated (new applications should use -RSA_generate_key_ex instead). RSA_generate_key works in the same was as -RSA_generate_key_ex except it uses "old style" call backs. See -L for further details. - -=head1 RETURN VALUE - -If key generation fails, RSA_generate_key() returns B. - -The error codes can be obtained by L. - -=head1 BUGS - -B is used with two different meanings. - -RSA_generate_key() goes into an infinite loop for illegal input values. - -=head1 SEE ALSO - -L, L, L, -L, L - -=head1 HISTORY - -The B argument was added in SSLeay 0.9.0. - -=cut diff --git a/src/lib/libcrypto/doc/RSA_get_ex_new_index.pod b/src/lib/libcrypto/doc/RSA_get_ex_new_index.pod deleted file mode 100644 index b1ac1167dd..0000000000 --- a/src/lib/libcrypto/doc/RSA_get_ex_new_index.pod +++ /dev/null @@ -1,122 +0,0 @@ -=pod - -=head1 NAME - -RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application -specific data to RSA structures - -=head1 SYNOPSIS - - #include - - int RSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int RSA_set_ex_data(RSA *r, int idx, void *arg); - - void *RSA_get_ex_data(RSA *r, int idx); - - typedef int CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, - int idx, long argl, void *argp); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -This has several potential uses, it can be used to cache data associated with -a structure (for example the hash of some part of the structure) or some -additional data (for example a handle to the data in an external library). - -Since the application data can be anything at all it is passed and retrieved -as a B type. - -The B function is initially called to "register" some -new application specific data. It takes three optional function pointers which -are called when the parent structure (in this case an RSA structure) is -initially created, when it is copied and when it is freed up. If any or all of -these function pointer arguments are not used they should be set to NULL. The -precise manner in which these function pointers are called is described in more -detail below. B also takes additional long and pointer -parameters which will be passed to the supplied functions but which otherwise -have no special meaning. It returns an B which should be stored -(typically in a static variable) and passed used in the B parameter in -the remaining functions. Each successful call to B -will return an index greater than any previously returned, this is important -because the optional functions are called in order of increasing index value. - -B is used to set application specific data, the data is -supplied in the B parameter and its precise meaning is up to the -application. - -B is used to retrieve application specific data. The data -is returned to the application, this will be the same value as supplied to -a previous B call. - -B is called when a structure is initially allocated (for example -with B. The parent structure members will not have any meaningful -values at this point. This function will typically be used to allocate any -application specific structure. - -B is called when a structure is being freed up. The dynamic parent -structure members should not be accessed because they will be freed up when -this function is called. - -B and B take the same parameters. B is a -pointer to the parent RSA structure. B is a the application specific data -(this wont be of much use in B. B is a pointer to the -B structure from the parent RSA structure: the functions -B and B can be called to manipulate -it. The B parameter is the index: this will be the same value returned by -B when the functions were initially registered. Finally -the B and B parameters are the values originally passed to the same -corresponding parameters when B was called. - -B is called when a structure is being copied. Pointers to the -destination and source B structures are passed in the B and -B parameters respectively. The B parameter is passed a pointer to -the source application data when the function is called, when the function -returns the value is copied to the destination: the application can thus modify -the data pointed to by B and have different values in the source and -destination. The B, B and B parameters are the same as those -in B and B. - -=head1 RETURN VALUES - -B returns a new index or -1 on failure (note 0 is a -valid index value). - -B returns 1 on success or 0 on failure. - -B returns the application data or 0 on failure. 0 may also -be valid application data but currently it can only fail if given an invalid -B parameter. - -B and B should return 0 for failure and 1 for success. - -On failure an error code can be obtained from -L. - -=head1 BUGS - -B is currently never called. - -The return value of B is ignored. - -The B function isn't very useful because no meaningful values are -present in the parent RSA structure when it is called. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() are -available since SSLeay 0.9.0. - -=cut diff --git a/src/lib/libcrypto/doc/RSA_new.pod b/src/lib/libcrypto/doc/RSA_new.pod deleted file mode 100644 index 0c85dc1d62..0000000000 --- a/src/lib/libcrypto/doc/RSA_new.pod +++ /dev/null @@ -1,39 +0,0 @@ -=pod - -=head1 NAME - -RSA_new, RSA_free - allocate and free RSA objects - -=head1 SYNOPSIS - - #include - - RSA * RSA_new(void); - - void RSA_free(RSA *rsa); - -=head1 DESCRIPTION - -RSA_new() allocates and initializes an B structure. It is equivalent to -calling RSA_new_method(NULL). - -RSA_free() frees the B structure and its components. The key is -erased before the memory is returned to the system. - -=head1 RETURN VALUES - -If the allocation fails, RSA_new() returns B and sets an error code that -can be obtained by L. Otherwise it returns a -pointer to the newly allocated structure. - -=head1 SEE ALSO - -L, L, -L, -L - -=head1 HISTORY - -RSA_new() and RSA_free() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/src/lib/libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod b/src/lib/libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod deleted file mode 100644 index 1c90b2b44d..0000000000 --- a/src/lib/libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod +++ /dev/null @@ -1,121 +0,0 @@ -=pod - -=head1 NAME - -RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1, -RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2, -RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP, -RSA_padding_add_SSLv23, RSA_padding_check_SSLv23, -RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption -padding - -=head1 SYNOPSIS - - #include - - int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen, - unsigned char *f, int fl); - - int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen, - unsigned char *f, int fl, int rsa_len); - - int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen, - unsigned char *f, int fl); - - int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen, - unsigned char *f, int fl, int rsa_len); - - int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen, - unsigned char *f, int fl, unsigned char *p, int pl); - - int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen, - unsigned char *f, int fl, int rsa_len, unsigned char *p, int pl); - - int RSA_padding_add_SSLv23(unsigned char *to, int tlen, - unsigned char *f, int fl); - - int RSA_padding_check_SSLv23(unsigned char *to, int tlen, - unsigned char *f, int fl, int rsa_len); - - int RSA_padding_add_none(unsigned char *to, int tlen, - unsigned char *f, int fl); - - int RSA_padding_check_none(unsigned char *to, int tlen, - unsigned char *f, int fl, int rsa_len); - -=head1 DESCRIPTION - -The RSA_padding_xxx_xxx() functions are called from the RSA encrypt, -decrypt, sign and verify functions. Normally they should not be called -from application programs. - -However, they can also be called directly to implement padding for other -asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and -RSA_padding_check_PKCS1_OAEP() may be used in an application combined -with B in order to implement OAEP with an encoding -parameter. - -RSA_padding_add_xxx() encodes B bytes from B so as to fit into -B bytes and stores the result at B. An error occurs if B -does not meet the size requirements of the encoding method. - -The following encoding methods are implemented: - -=over 4 - -=item PKCS1_type_1 - -PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures - -=item PKCS1_type_2 - -PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2) - -=item PKCS1_OAEP - -PKCS #1 v2.0 EME-OAEP - -=item SSLv23 - -PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification - -=item none - -simply copy the data - -=back - -RSA_padding_check_xxx() verifies that the B bytes at B contain -a valid encoding for a B byte RSA key in the respective -encoding method and stores the recovered data of at most B bytes -(for B: of size B) -at B. - -For RSA_padding_xxx_OAEP(), B

points to the encoding parameter -of length B. B

may be B if B is 0. - -=head1 RETURN VALUES - -The RSA_padding_add_xxx() functions return 1 on success, 0 on error. -The RSA_padding_check_xxx() functions return the length of the -recovered data, -1 on error. Error codes can be obtained by calling -L. - -=head1 SEE ALSO - -L, -L, -L, L - -=head1 HISTORY - -RSA_padding_add_PKCS1_type_1(), RSA_padding_check_PKCS1_type_1(), -RSA_padding_add_PKCS1_type_2(), RSA_padding_check_PKCS1_type_2(), -RSA_padding_add_SSLv23(), RSA_padding_check_SSLv23(), -RSA_padding_add_none() and RSA_padding_check_none() appeared in -SSLeay 0.9.0. - -RSA_padding_add_PKCS1_OAEP() and RSA_padding_check_PKCS1_OAEP() were -added in OpenSSL 0.9.2b. - -=cut diff --git a/src/lib/libcrypto/doc/RSA_print.pod b/src/lib/libcrypto/doc/RSA_print.pod deleted file mode 100644 index c971e91f4d..0000000000 --- a/src/lib/libcrypto/doc/RSA_print.pod +++ /dev/null @@ -1,49 +0,0 @@ -=pod - -=head1 NAME - -RSA_print, RSA_print_fp, -DSAparams_print, DSAparams_print_fp, DSA_print, DSA_print_fp, -DHparams_print, DHparams_print_fp - print cryptographic parameters - -=head1 SYNOPSIS - - #include - - int RSA_print(BIO *bp, RSA *x, int offset); - int RSA_print_fp(FILE *fp, RSA *x, int offset); - - #include - - int DSAparams_print(BIO *bp, DSA *x); - int DSAparams_print_fp(FILE *fp, DSA *x); - int DSA_print(BIO *bp, DSA *x, int offset); - int DSA_print_fp(FILE *fp, DSA *x, int offset); - - #include - - int DHparams_print(BIO *bp, DH *x); - int DHparams_print_fp(FILE *fp, DH *x); - -=head1 DESCRIPTION - -A human-readable hexadecimal output of the components of the RSA -key, DSA parameters or key or DH parameters is printed to B or B. - -The output lines are indented by B spaces. - -=head1 RETURN VALUES - -These functions return 1 on success, 0 on error. - -=head1 SEE ALSO - -L, L, L, L - -=head1 HISTORY - -RSA_print(), RSA_print_fp(), DSA_print(), DSA_print_fp(), DH_print(), -DH_print_fp() are available in all versions of SSLeay and OpenSSL. -DSAparams_print() and DSAparams_print_fp() were added in SSLeay 0.8. - -=cut diff --git a/src/lib/libcrypto/doc/RSA_private_encrypt.pod b/src/lib/libcrypto/doc/RSA_private_encrypt.pod deleted file mode 100644 index aa2bc1bd76..0000000000 --- a/src/lib/libcrypto/doc/RSA_private_encrypt.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - -RSA_private_encrypt, RSA_public_decrypt - low level signature operations - -=head1 SYNOPSIS - - #include - - int RSA_private_encrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - - int RSA_public_decrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - -=head1 DESCRIPTION - -These functions handle RSA signatures at a low level. - -RSA_private_encrypt() signs the B bytes at B (usually a -message digest with an algorithm identifier) using the private key -B and stores the signature in B. B must point to -B bytes of memory. - -B denotes one of the following modes: - -=over 4 - -=item RSA_PKCS1_PADDING - -PKCS #1 v1.5 padding. This function does not handle the B -specified in PKCS #1. When generating or verifying PKCS #1 signatures, -L and L should be used. - -=item RSA_NO_PADDING - -Raw RSA signature. This mode should I be used to implement -cryptographically sound padding modes in the application code. -Signing user data directly with RSA is insecure. - -=back - -RSA_public_decrypt() recovers the message digest from the B -bytes long signature at B using the signer's public key -B. B must point to a memory section large enough to hold the -message digest (which is smaller than B). B is the padding mode that was used to sign the data. - -=head1 RETURN VALUES - -RSA_private_encrypt() returns the size of the signature (i.e., -RSA_size(rsa)). RSA_public_decrypt() returns the size of the -recovered message digest. - -On error, -1 is returned; the error codes can be -obtained by L. - -=head1 SEE ALSO - -L, L, -L, L - -=head1 HISTORY - -The B argument was added in SSLeay 0.8. RSA_NO_PADDING is -available since SSLeay 0.9.0. - -=cut diff --git a/src/lib/libcrypto/doc/RSA_public_encrypt.pod b/src/lib/libcrypto/doc/RSA_public_encrypt.pod deleted file mode 100644 index 4bbee53f09..0000000000 --- a/src/lib/libcrypto/doc/RSA_public_encrypt.pod +++ /dev/null @@ -1,82 +0,0 @@ -=pod - -=head1 NAME - -RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography - -=head1 SYNOPSIS - - #include - - int RSA_public_encrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - - int RSA_private_decrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - -=head1 DESCRIPTION - -RSA_public_encrypt() encrypts the B bytes at B (usually a -session key) using the public key B and stores the ciphertext in -B. B must point to RSA_size(B) bytes of memory. - -B denotes one of the following modes: - -=over 4 - -=item RSA_PKCS1_PADDING - -PKCS #1 v1.5 padding. This currently is the most widely used mode. - -=item RSA_PKCS1_OAEP_PADDING - -EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty -encoding parameter. This mode is recommended for all new applications. - -=item RSA_SSLV23_PADDING - -PKCS #1 v1.5 padding with an SSL-specific modification that denotes -that the server is SSL3 capable. - -=item RSA_NO_PADDING - -Raw RSA encryption. This mode should I be used to implement -cryptographically sound padding modes in the application code. -Encrypting user data directly with RSA is insecure. - -=back - -B must be less than RSA_size(B) - 11 for the PKCS #1 v1.5 -based padding modes, less than RSA_size(B) - 41 for -RSA_PKCS1_OAEP_PADDING and exactly RSA_size(B) for RSA_NO_PADDING. - -RSA_private_decrypt() decrypts the B bytes at B using the -private key B and stores the plaintext in B. B must point -to a memory section large enough to hold the decrypted data (which is -smaller than RSA_size(B)). B is the padding mode that -was used to encrypt the data. - -=head1 RETURN VALUES - -RSA_public_encrypt() returns the size of the encrypted data (i.e., -RSA_size(B)). RSA_private_decrypt() returns the size of the -recovered plaintext. - -On error, -1 is returned; the error codes can be -obtained by L. - -=head1 CONFORMING TO - -SSL, PKCS #1 v2.0 - -=head1 SEE ALSO - -L, L, L, -L - -=head1 HISTORY - -The B argument was added in SSLeay 0.8. RSA_NO_PADDING is -available since SSLeay 0.9.0, OAEP was added in OpenSSL 0.9.2b. - -=cut diff --git a/src/lib/libcrypto/doc/RSA_set_method.pod b/src/lib/libcrypto/doc/RSA_set_method.pod deleted file mode 100644 index 3f50a89e5c..0000000000 --- a/src/lib/libcrypto/doc/RSA_set_method.pod +++ /dev/null @@ -1,201 +0,0 @@ -=pod - -=head1 NAME - -RSA_set_default_method, RSA_get_default_method, RSA_set_method, -RSA_get_method, RSA_PKCS1_SSLeay, RSA_null_method, RSA_flags, -RSA_new_method, RSA_get_default_openssl_method, -RSA_set_default_openssl_method - select RSA method - -=head1 SYNOPSIS - - #include - - void RSA_set_default_method(const RSA_METHOD *meth); - - RSA_METHOD *RSA_get_default_method(void); - - int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); - - RSA_METHOD *RSA_get_method(const RSA *rsa); - - RSA_METHOD *RSA_PKCS1_SSLeay(void); - - RSA_METHOD *RSA_null_method(void); - - int RSA_flags(const RSA *rsa); - - RSA *RSA_new_method(RSA_METHOD *method); - -=head1 DESCRIPTION - -An B specifies the functions that OpenSSL uses for RSA -operations. By modifying the method, alternative implementations such as -hardware accelerators may be used. IMPORTANT: See the NOTES section for -important information about how these RSA API functions are affected by the -use of B API calls. - -Initially, the default RSA_METHOD is the OpenSSL internal implementation, -as returned by RSA_PKCS1_SSLeay(). - -RSA_set_default_method() makes B the default method for all RSA -structures created later. B: This is true only whilst no ENGINE has -been set as a default for RSA, so this function is no longer recommended. - -RSA_get_default_method() returns a pointer to the current default -RSA_METHOD. However, the meaningfulness of this result is dependent on -whether the ENGINE API is being used, so this function is no longer -recommended. - -RSA_set_method() selects B to perform all operations using the key -B. This will replace the RSA_METHOD used by the RSA key and if the -previous method was supplied by an ENGINE, the handle to that ENGINE will -be released during the change. It is possible to have RSA keys that only -work with certain RSA_METHOD implementations (eg. from an ENGINE module -that supports embedded hardware-protected keys), and in such cases -attempting to change the RSA_METHOD for the key can have unexpected -results. - -RSA_get_method() returns a pointer to the RSA_METHOD being used by B. -This method may or may not be supplied by an ENGINE implementation, but if -it is, the return value can only be guaranteed to be valid as long as the -RSA key itself is valid and does not have its implementation changed by -RSA_set_method(). - -RSA_flags() returns the B that are set for B's current -RSA_METHOD. See the BUGS section. - -RSA_new_method() allocates and initializes an RSA structure so that -B will be used for the RSA operations. If B is NULL, the -default ENGINE for RSA operations is used, and if no default ENGINE is set, -the RSA_METHOD controlled by RSA_set_default_method() is used. - -RSA_flags() returns the B that are set for B's current method. - -RSA_new_method() allocates and initializes an B structure so that -B will be used for the RSA operations. If B is B, -the default method is used. - -=head1 THE RSA_METHOD STRUCTURE - - typedef struct rsa_meth_st - { - /* name of the implementation */ - const char *name; - - /* encrypt */ - int (*rsa_pub_enc)(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - - /* verify arbitrary data */ - int (*rsa_pub_dec)(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - - /* sign arbitrary data */ - int (*rsa_priv_enc)(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - - /* decrypt */ - int (*rsa_priv_dec)(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - - /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some - implementations) */ - int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa); - - /* compute r = a ^ p mod m (May be NULL for some implementations) */ - int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); - - /* called at RSA_new */ - int (*init)(RSA *rsa); - - /* called at RSA_free */ - int (*finish)(RSA *rsa); - - /* RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key - * operations, even if p,q,dmp1,dmq1,iqmp - * are NULL - * RSA_FLAG_SIGN_VER - enable rsa_sign and rsa_verify - * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match - */ - int flags; - - char *app_data; /* ?? */ - - /* sign. For backward compatibility, this is used only - * if (flags & RSA_FLAG_SIGN_VER) - */ - int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len, - unsigned char *sigret, unsigned int *siglen, RSA *rsa); - - /* verify. For backward compatibility, this is used only - * if (flags & RSA_FLAG_SIGN_VER) - */ - int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len, - unsigned char *sigbuf, unsigned int siglen, RSA *rsa); - - } RSA_METHOD; - -=head1 RETURN VALUES - -RSA_PKCS1_SSLeay(), RSA_PKCS1_null_method(), RSA_get_default_method() -and RSA_get_method() return pointers to the respective RSA_METHODs. - -RSA_set_method() returns a pointer to the old RSA_METHOD implementation -that was replaced. However, this return value should probably be ignored -because if it was supplied by an ENGINE, the pointer could be invalidated -at any time if the ENGINE is unloaded (in fact it could be unloaded as a -result of the RSA_set_method() function releasing its handle to the -ENGINE). For this reason, the return type may be replaced with a B -declaration in a future release. - -RSA_new_method() returns NULL and sets an error code that can be obtained -by L if the allocation fails. Otherwise -it returns a pointer to the newly allocated structure. - -=head1 NOTES - -As of version 0.9.7, RSA_METHOD implementations are grouped together with -other algorithmic APIs (eg. DSA_METHOD, EVP_CIPHER, etc) into B -modules. If a default ENGINE is specified for RSA functionality using an -ENGINE API function, that will override any RSA defaults set using the RSA -API (ie. RSA_set_default_method()). For this reason, the ENGINE API is the -recommended way to control default implementations for use in RSA and other -cryptographic algorithms. - -=head1 BUGS - -The behaviour of RSA_flags() is a mis-feature that is left as-is for now -to avoid creating compatibility problems. RSA functionality, such as the -encryption functions, are controlled by the B value in the RSA key -itself, not by the B value in the RSA_METHOD attached to the RSA key -(which is what this function returns). If the flags element of an RSA key -is changed, the changes will be honoured by RSA functionality but will not -be reflected in the return value of the RSA_flags() function - in effect -RSA_flags() behaves more like an RSA_default_flags() function (which does -not currently exist). - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -RSA_new_method() and RSA_set_default_method() appeared in SSLeay 0.8. -RSA_get_default_method(), RSA_set_method() and RSA_get_method() as -well as the rsa_sign and rsa_verify components of RSA_METHOD were -added in OpenSSL 0.9.4. - -RSA_set_default_openssl_method() and RSA_get_default_openssl_method() -replaced RSA_set_default_method() and RSA_get_default_method() -respectively, and RSA_set_method() and RSA_new_method() were altered to use -Bs rather than Bs during development of the engine -version of OpenSSL 0.9.6. For 0.9.7, the handling of defaults in the ENGINE -API was restructured so that this change was reversed, and behaviour of the -other functions resembled more closely the previous behaviour. The -behaviour of defaults in the ENGINE API now transparently overrides the -behaviour of defaults in the RSA API without requiring changing these -function prototypes. - -=cut diff --git a/src/lib/libcrypto/doc/RSA_sign.pod b/src/lib/libcrypto/doc/RSA_sign.pod deleted file mode 100644 index 51587bdc41..0000000000 --- a/src/lib/libcrypto/doc/RSA_sign.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -RSA_sign, RSA_verify - RSA signatures - -=head1 SYNOPSIS - - #include - - int RSA_sign(int type, const unsigned char *m, unsigned int m_len, - unsigned char *sigret, unsigned int *siglen, RSA *rsa); - - int RSA_verify(int type, const unsigned char *m, unsigned int m_len, - unsigned char *sigbuf, unsigned int siglen, RSA *rsa); - -=head1 DESCRIPTION - -RSA_sign() signs the message digest B of size B using the -private key B as specified in PKCS #1 v2.0. It stores the -signature in B and the signature size in B. B -must point to RSA_size(B) bytes of memory. -Note that PKCS #1 adds meta-data, placing limits on the size of the -key that can be used. -See L for lower-level -operations. - -B denotes the message digest algorithm that was used to generate -B. It usually is one of B, B and B; -see L for details. If B is B, -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 of size B -matches a given message digest B of size B. B denotes -the message digest algorithm that was used to generate the signature. -B is the signer's public key. - -=head1 RETURN VALUES - -RSA_sign() returns 1 on success, 0 otherwise. RSA_verify() returns 1 -on successful verification, 0 otherwise. - -The error codes can be obtained by L. - -=head1 CONFORMING TO - -SSL, PKCS #1 v2.0 - -=head1 SEE ALSO - -L, L, -L, L, -L - -=head1 HISTORY - -RSA_sign() and RSA_verify() are available in all versions of SSLeay -and OpenSSL. - -=cut diff --git a/src/lib/libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod b/src/lib/libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod deleted file mode 100644 index 664b46174b..0000000000 --- a/src/lib/libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING - RSA signatures - -=head1 SYNOPSIS - - #include - - int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, - unsigned int m_len, unsigned char *sigret, unsigned int *siglen, - RSA *rsa); - - int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m, - unsigned int m_len, unsigned char *sigbuf, unsigned int siglen, - RSA *rsa); - -=head1 DESCRIPTION - -RSA_sign_ASN1_OCTET_STRING() signs the octet string B of size -B using the private key B represented in DER using PKCS #1 -padding. It stores the signature in B and the signature size -in B. B must point to B bytes of -memory. - -B is ignored. - -RSA_verify_ASN1_OCTET_STRING() verifies that the signature B -of size B is the DER representation of a given octet string -B of size B. B is ignored. B is the signer's -public key. - -=head1 RETURN VALUES - -RSA_sign_ASN1_OCTET_STRING() returns 1 on success, 0 otherwise. -RSA_verify_ASN1_OCTET_STRING() returns 1 on successful verification, 0 -otherwise. - -The error codes can be obtained by L. - -=head1 BUGS - -These functions serve no recognizable purpose. - -=head1 SEE ALSO - -L, L, -L, L, L, -L - -=head1 HISTORY - -RSA_sign_ASN1_OCTET_STRING() and RSA_verify_ASN1_OCTET_STRING() were -added in SSLeay 0.8. - -=cut diff --git a/src/lib/libcrypto/doc/RSA_size.pod b/src/lib/libcrypto/doc/RSA_size.pod deleted file mode 100644 index 5b7f835f95..0000000000 --- a/src/lib/libcrypto/doc/RSA_size.pod +++ /dev/null @@ -1,33 +0,0 @@ -=pod - -=head1 NAME - -RSA_size - get RSA modulus size - -=head1 SYNOPSIS - - #include - - int RSA_size(const RSA *rsa); - -=head1 DESCRIPTION - -This function returns the RSA modulus size in bytes. It can be used to -determine how much memory must be allocated for an RSA encrypted -value. - -Bn> must not be B. - -=head1 RETURN VALUE - -The size in bytes. - -=head1 SEE ALSO - -L - -=head1 HISTORY - -RSA_size() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod b/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod deleted file mode 100644 index 11515d0ace..0000000000 --- a/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod +++ /dev/null @@ -1,63 +0,0 @@ -=pod - -=head1 NAME - -d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey, -d2i_RSA_PUBKEY, i2d_RSA_PUBKEY, i2d_Netscape_RSA, -d2i_Netscape_RSA - RSA public and private key encoding functions. - -=head1 SYNOPSIS - - #include - #include - - RSA * d2i_RSAPublicKey(RSA **a, const unsigned char **pp, long length); - - int i2d_RSAPublicKey(RSA *a, unsigned char **pp); - - RSA * d2i_RSA_PUBKEY(RSA **a, const unsigned char **pp, long length); - - int i2d_RSA_PUBKEY(RSA *a, unsigned char **pp); - - RSA * d2i_RSAPrivateKey(RSA **a, const unsigned char **pp, long length); - - int i2d_RSAPrivateKey(RSA *a, unsigned char **pp); - - int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)()); - - RSA * d2i_Netscape_RSA(RSA **a, const unsigned char **pp, long length, int (*cb)()); - -=head1 DESCRIPTION - -d2i_RSAPublicKey() and i2d_RSAPublicKey() decode and encode a PKCS#1 -RSAPublicKey structure. - -d2i_RSA_PUBKEY() and i2d_RSA_PUBKEY() decode and encode an RSA public key using -a SubjectPublicKeyInfo (certificate public key) structure. - -d2i_RSAPrivateKey(), i2d_RSAPrivateKey() decode and encode a PKCS#1 -RSAPrivateKey structure. - -d2i_Netscape_RSA(), i2d_Netscape_RSA() decode and encode an RSA private key in -NET format. - -The usage of all of these functions is similar to the d2i_X509() and -i2d_X509() described in the L manual page. - -=head1 NOTES - -The B structure passed to the private key encoding functions should have -all the PKCS#1 private key components present. - -The data encoded by the private key functions is unencrypted and therefore -offers no private key security. - -The NET format functions are present to provide compatibility with certain very -old software. This format has some severe security weaknesses and should be -avoided if possible. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libcrypto/doc/rsa.pod b/src/lib/libcrypto/doc/rsa.pod deleted file mode 100644 index 829ce24701..0000000000 --- a/src/lib/libcrypto/doc/rsa.pod +++ /dev/null @@ -1,123 +0,0 @@ -=pod - -=head1 NAME - -rsa - RSA public key cryptosystem - -=head1 SYNOPSIS - - #include - #include - - RSA * RSA_new(void); - void RSA_free(RSA *rsa); - - int RSA_public_encrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - int RSA_private_decrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - int RSA_private_encrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa,int padding); - int RSA_public_decrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa,int padding); - - int RSA_sign(int type, unsigned char *m, unsigned int m_len, - unsigned char *sigret, unsigned int *siglen, RSA *rsa); - int RSA_verify(int type, unsigned char *m, unsigned int m_len, - unsigned char *sigbuf, unsigned int siglen, RSA *rsa); - - int RSA_size(const RSA *rsa); - - RSA *RSA_generate_key(int num, unsigned long e, - void (*callback)(int,int,void *), void *cb_arg); - - int RSA_check_key(RSA *rsa); - - int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); - void RSA_blinding_off(RSA *rsa); - - void RSA_set_default_method(const RSA_METHOD *meth); - const RSA_METHOD *RSA_get_default_method(void); - int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); - const RSA_METHOD *RSA_get_method(const RSA *rsa); - RSA_METHOD *RSA_PKCS1_SSLeay(void); - RSA_METHOD *RSA_null_method(void); - int RSA_flags(const RSA *rsa); - RSA *RSA_new_method(ENGINE *engine); - - int RSA_print(BIO *bp, RSA *x, int offset); - int RSA_print_fp(FILE *fp, RSA *x, int offset); - - int RSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), - int (*dup_func)(), void (*free_func)()); - int RSA_set_ex_data(RSA *r,int idx,char *arg); - char *RSA_get_ex_data(RSA *r, int idx); - - int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, - unsigned int m_len, unsigned char *sigret, unsigned int *siglen, - RSA *rsa); - int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m, - unsigned int m_len, unsigned char *sigbuf, unsigned int siglen, - RSA *rsa); - -=head1 DESCRIPTION - -These functions implement RSA public key encryption and signatures -as defined in PKCS #1 v2.0 [RFC 2437]. - -The B structure consists of several BIGNUM components. It can -contain public as well as private RSA keys: - - struct - { - BIGNUM *n; // public modulus - BIGNUM *e; // public exponent - BIGNUM *d; // private exponent - BIGNUM *p; // secret prime factor - BIGNUM *q; // secret prime factor - BIGNUM *dmp1; // d mod (p-1) - BIGNUM *dmq1; // d mod (q-1) - BIGNUM *iqmp; // q^-1 mod p - // ... - }; - RSA - -In public keys, the private exponent and the related secret values are -B. - -B

, B, B, B and B may be B in private -keys, but the RSA operations are much faster when these values are -available. - -Note that RSA keys may use non-standard B implementations, -either directly or by the use of B modules. In some cases (eg. an -ENGINE providing support for hardware-embedded keys), these BIGNUM values -will not be used by the implementation or may be used for alternative data -storage. For this reason, applications should generally avoid using RSA -structure elements directly and instead use API functions to query or -modify keys. - -=head1 CONFORMING TO - -SSL, PKCS #1 v2.0 - -=head1 PATENTS - -RSA was covered by a US patent which expired in September 2000. - -=head1 SEE ALSO - -L, L, L, L, -L, L, L, -L, -L, L, -L, -L, -L, -L, L, -L, -L, -L, -L - -=cut diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 0b3a08a7d3..8bc8ffb6aa 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.44 2016/11/03 15:48:22 schwarze Exp $ +# $OpenBSD: Makefile,v 1.45 2016/11/04 10:17:17 schwarze Exp $ .include # for NOMAN @@ -137,6 +137,19 @@ MAN= \ RAND_cleanup.3 \ RAND_load_file.3 \ RAND_set_rand_method.3 \ + RSA_blinding_on.3 \ + RSA_check_key.3 \ + RSA_generate_key.3 \ + RSA_get_ex_new_index.3 \ + RSA_new.3 \ + RSA_padding_add_PKCS1_type_1.3 \ + RSA_print.3 \ + RSA_private_encrypt.3 \ + RSA_public_encrypt.3 \ + RSA_set_method.3 \ + RSA_sign.3 \ + RSA_sign_ASN1_OCTET_STRING.3 \ + RSA_size.3 \ SMIME_read_PKCS7.3 \ SMIME_write_PKCS7.3 \ UI_new.3 \ @@ -144,27 +157,16 @@ MAN= \ crypto.3 \ d2i_ASN1_OBJECT.3 \ d2i_PKCS8PrivateKey_bio.3 \ + d2i_RSAPublicKey.3 \ des_read_pw.3 \ evp.3 \ i2d_PKCS7_bio_stream.3 \ lh_new.3 \ + rsa.3 \ GENMAN= \ RC4.3 \ RIPEMD160.3 \ - RSA_blinding_on.3 \ - RSA_check_key.3 \ - RSA_generate_key.3 \ - RSA_get_ex_new_index.3 \ - RSA_new.3 \ - RSA_padding_add_PKCS1_type_1.3 \ - RSA_print.3 \ - RSA_private_encrypt.3 \ - RSA_public_encrypt.3 \ - RSA_set_method.3 \ - RSA_sign.3 \ - RSA_sign_ASN1_OCTET_STRING.3 \ - RSA_size.3 \ SHA1.3 \ X509_NAME_ENTRY_get_object.3 \ X509_NAME_add_entry_by_txt.3 \ @@ -182,7 +184,6 @@ GENMAN= \ d2i_DHparams.3 \ d2i_DSAPublicKey.3 \ d2i_ECPKParameters.3 \ - d2i_RSAPublicKey.3 \ d2i_X509.3 \ d2i_X509_ALGOR.3 \ d2i_X509_CRL.3 \ @@ -194,7 +195,6 @@ GENMAN= \ ec.3 \ engine.3 \ lh_stats.3 \ - rsa.3 \ x509.3 \ MAN+= ${GENMAN} diff --git a/src/lib/libcrypto/man/RSA_blinding_on.3 b/src/lib/libcrypto/man/RSA_blinding_on.3 new file mode 100644 index 0000000000..a2d22c9093 --- /dev/null +++ b/src/lib/libcrypto/man/RSA_blinding_on.3 @@ -0,0 +1,46 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt RSA_BLINDING_ON 3 +.Os +.Sh NAME +.Nm RSA_blinding_on , +.Nm RSA_blinding_off +.Nd protect the RSA operation from timing attacks +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft int +.Fo RSA_blinding_on +.Fa "RSA *rsa" +.Fa "BN_CTX *ctx" +.Fc +.Ft void +.Fo RSA_blinding_off +.Fa "RSA *rsa" +.Fc +.Sh DESCRIPTION +RSA is vulnerable to timing attacks. +In a setup where attackers can measure the time of RSA decryption or +signature operations, blinding must be used to protect the RSA operation +from that attack. +.Pp +.Fn RSA_blinding_on +turns blinding on for key +.Fa rsa +and generates a random blinding factor. +.Fa ctx +is +.Dv NULL +or a pre-allocated and initialized +.Vt BN_CTX . +.Pp +.Fn RSA_blinding_off +turns blinding off and frees the memory used for the blinding factor. +.Sh RETURN VALUES +.Fn RSA_blinding_on +returns 1 on success, and 0 if an error occurred. +.Sh SEE ALSO +.Xr rsa 3 +.Sh HISTORY +.Fn RSA_blinding_on +and +.Fn RSA_blinding_off +appeared in SSLeay 0.9.0. diff --git a/src/lib/libcrypto/man/RSA_check_key.3 b/src/lib/libcrypto/man/RSA_check_key.3 new file mode 100644 index 0000000000..c57ed4b4db --- /dev/null +++ b/src/lib/libcrypto/man/RSA_check_key.3 @@ -0,0 +1,97 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt RSA_CHECK_KEY 3 +.Os +.Sh NAME +.Nm RSA_check_key +.Nd validate private RSA keys +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft int +.Fo RSA_check_key +.Fa "RSA *rsa" +.Fc +.Sh DESCRIPTION +This function validates RSA keys. +It checks that +.Fa rsa->p +and +.Fa rsa->q +are in fact prime, and that +.Fa rsa->n +satifies n = p*q. +.Pp +It also checks that +.Fa rsa->d +and +.Fa rsa->e +satisfy d*e = 1 mod ((p-1)*(q-1)), +and that +.Fa rsa->dmp1 , +.Fa rsa->dmq1 , +and +.Fa resa->iqmp +are set correctly or are +.Dv NULL . +.Pp +As such, this function cannot be used with any arbitrary +.Vt RSA +key object, even if it is otherwise fit for regular RSA operation. +.Pp +This function does not work on RSA public keys that have only the +modulus and public exponent elements populated. +It performs integrity checks on all the RSA key material, so the +.Vt RSA +key structure must contain all the private key data too. +.Pp +Unlike most other RSA functions, this function does +.Sy not +work transparently with any underlying +.Vt ENGINE +implementation because it uses the key data in the +.Vt RSA +structure directly. +An +.Vt ENGINE +implementation can override the way key data is stored and handled, +and can even provide support for HSM keys - in which case the +.Vt RSA +structure may contain +.Sy no +key data at all! +If the +.Vt ENGINE +in question is only being used for acceleration or analysis purposes, +then in all likelihood the RSA key data is complete and untouched, +but this can't be assumed in the general case. +.Sh RETURN VALUE +.Fn RSA_check_key +returns 1 if +.Fa rsa +is a valid RSA key, and 0 otherwise. +-1 is returned if an error occurs while checking the key. +.Pp +If the key is invalid or an error occurred, the reason code can be +obtained using +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ERR_get_error 3 , +.Xr rsa 3 +.Sh HISTORY +.Fn RSA_check_key +appeared in OpenSSL 0.9.4. +.Sh BUGS +A method of verifying the RSA key using opaque RSA API functions might +need to be considered. +Right now +.Fn RSA_check_key +simply uses the +.Vt RSA +structure elements directly, bypassing the +.Vt RSA_METHOD +table altogether (and completely violating encapsulation and +object-orientation in the process). +The best fix will probably be to introduce a check_key() handler +to the +.Vt RSA_METHOD +function table so that alternative implementations can also provide +their own verifiers. diff --git a/src/lib/libcrypto/man/RSA_generate_key.3 b/src/lib/libcrypto/man/RSA_generate_key.3 new file mode 100644 index 0000000000..a9e72c6594 --- /dev/null +++ b/src/lib/libcrypto/man/RSA_generate_key.3 @@ -0,0 +1,105 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt RSA_GENERATE_KEY 3 +.Os +.Sh NAME +.Nm RSA_generate_key_ex , +.Nm RSA_generate_key +.Nd generate RSA key pair +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft int +.Fo RSA_generate_key_ex +.Fa "RSA *rsa" +.Fa "int bits" +.Fa "BIGNUM *e" +.Fa "BN_GENCB *cb" +.Fc +.Pp +Deprecated: +.Pp +.Ft RSA * +.Fo RSA_generate_key +.Fa "int num" +.Fa "unsigned long e" +.Fa "void (*callback)(int, int, void *)" +.Fa "void *cb_arg" +.Fc +.Sh DESCRIPTION +.Fn RSA_generate_key_ex +generates a key pair and stores it in +.Fa rsa . +.Pp +The modulus size will be of length +.Fa bits , +and the public exponent will be +.Fa e . +Key sizes with +.Fa num +< 1024 should be considered insecure. +The exponent is an odd number, typically 3, 17 or 65537. +.Pp +A callback function may be used to provide feedback about the progress +of the key generation. +If +.Fa cb +is not +.Dv NULL , +it will be called as follows using the +.Xr BN_GENCB_call 3 +function: +.Bl -bullet +.It +While a random prime number is generated, it is called as described in +.Xr BN_generate_prime 3 . +.It +When the +.Fa n Ns -th +randomly generated prime is rejected as not suitable for +the key, +.Fn BN_GENCB_call cb 2 n +is called. +.It +When a random p has been found with p-1 relatively prime to +.Fa e , +it is called as +.Fn BN_GENCB_call cb 3 0 . +.El +.Pp +The process is then repeated for prime q with +.Fn BN_GENCB_call cb 3 1 . +.Pp +.Fn RSA_generate_key +is deprecated. +New applications should use +.Fn RSA_generate_key_ex +instead. +.Fn RSA_generate_key +works in the same was as +.Fn RSA_generate_key_ex +except it uses "old style" call backs. +See +.Xr BN_generate_prime 3 +for further details. +.Sh RETURN VALUE +If key generation fails, +.Fn RSA_generate_key +returns +.Dv NULL . +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr BN_generate_prime 3 , +.Xr ERR_get_error 3 , +.Xr rsa 3 , +.Xr RSA_free 3 +.Sh HISTORY +The +.Fa cb_arg +argument was added in SSLeay 0.9.0. +.Sh BUGS +.Fn BN_GENCB_call cb 2 x +is used with two different meanings. +.Pp +.Fn RSA_generate_key +goes into an infinite loop for illegal input values. diff --git a/src/lib/libcrypto/man/RSA_get_ex_new_index.3 b/src/lib/libcrypto/man/RSA_get_ex_new_index.3 new file mode 100644 index 0000000000..b61084a18e --- /dev/null +++ b/src/lib/libcrypto/man/RSA_get_ex_new_index.3 @@ -0,0 +1,227 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt RSA_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm RSA_get_ex_new_index , +.Nm RSA_set_ex_data , +.Nm RSA_get_ex_data +.Nd add application specific data to RSA structures +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft int +.Fo RSA_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fo RSA_set_ex_data +.Fa "RSA *r" +.Fa "int idx" +.Fa "void *arg" +.Fc +.Ft void * +.Fo RSA_get_ex_data +.Fa "RSA *r" +.Fa "int idx" +.Fc +.Ft typedef int +.Fo CRYPTO_EX_new +.Fa "void *parent" +.Fa "void *ptr" +.Fa "CRYPTO_EX_DATA *ad" +.Fa "int idx" +.Fa "long argl" +.Fa "void *argp" +.Fc +.Ft typedef void +.Fo CRYPTO_EX_free +.Fa "void *parent" +.Fa "void *ptr" +.Fa "CRYPTO_EX_DATA *ad" +.Fa "int idx" +.Fa "long argl" +.Fa "void *argp" +.Fc +.Ft typedef int +.Fo CRYPTO_EX_dup +.Fa "CRYPTO_EX_DATA *to" +.Fa "CRYPTO_EX_DATA *from" +.Fa "void *from_d" +.Fa "int idx" +.Fa "long argl" +.Fa "void *argp" +.Fc +.Sh DESCRIPTION +Several OpenSSL structures can have application specific data attached +to them. +This has several potential uses, it can be used to cache data associated +with a structure (for example the hash of some part of the structure) or +some additional data (for example a handle to the data in an external +library). +.Pp +Since the application data can be anything at all it is passed and +retrieved as a +.Vt void * +type. +.Pp +The +.Fn RSA_get_ex_new_index +function is initially called to "register" some new application specific +data. +It takes three optional function pointers which are called when the +parent structure (in this case an RSA structure) is initially created, +when it is copied and when it is freed up. +If any or all of these function pointer arguments are not used, they +should be set to +.Dv NULL . +The precise manner in which these function pointers are called is +described in more detail below. +.Fn RSA_get_ex_new_index +also takes additional long and pointer parameters which will be passed +to the supplied functions but which otherwise have no special meaning. +It returns an index which should be stored (typically in a static +variable) and passed as the +.Fa idx +parameter in the remaining functions. +Each successful call to +.Fn RSA_get_ex_new_index +will return an index greater than any previously returned. +This is +important because the optional functions are called in order of +increasing index value. +.Pp +.Fn RSA_set_ex_data +is used to set application specific data, the data is supplied in the +.Fa arg +parameter and its precise meaning is up to the application. +.Pp +.Fn RSA_get_ex_data +is used to retrieve application specific data. +The data is returned to the application, this will be the same value as +supplied to a previous +.Fn RSA_set_ex_data +call. +.Pp +.Fa new_func +is called when a structure is initially allocated (for example with +.Xr RSA_new 3 . +The parent structure members will not have any meaningful values at this +point. +This function will typically be used to allocate any application +specific structure. +.Pp +.Fa free_func +is called when a structure is being freed up. +The dynamic parent structure members should not be accessed because they +will be freed up when this function is called. +.Pp +.Fa new_func +and +.Fa free_func +take the same parameters. +.Fa parent +is a pointer to the parent +.Vt RSA +structure. +.Fa ptr +is the application specific data (this won't be of much use in +.Fa new_func ) . +.Fa ad +is a pointer to the +.Vt CRYPTO_EX_DATA +structure from the parent +.Vt RSA +structure: the functions +.Fn CRYPTO_get_ex_data +and +.Fn CRYPTO_set_ex_data +can be called to manipulate it. +The +.Fa idx +parameter is the index: this will be the same value returned by +.Fn RSA_get_ex_new_index +when the functions were initially registered. +Finally the +.Fa argl +and +.Fa argp +parameters are the values originally passed to the same corresponding +parameters when +.Fn RSA_get_ex_new_index +was called. +.Pp +.Fa dup_func +is called when a structure is being copied. +Pointers to the destination and source +.Vt CRYPTO_EX_DATA +structures are passed in the +.Fa to +and +.Fa from +parameters, respectively. +The +.Fa from_d +parameter is passed a pointer to the source application data when the +function is called. +When the function returns, the value is copied to the destination: +the application can thus modify the data pointed to by +.Fa from_d +and have different values in the source and destination. +The +.Fa idx , +.Fa argl , +and +.Fa argp +parameters are the same as those in +.Fa new_func +and +.Fa free_func . +.Sh RETURN VALUES +.Fn RSA_get_ex_new_index +returns a new index or -1 on failure. +Note that 0 is a valid index value. +.Pp +.Fn RSA_set_ex_data +returns 1 on success or 0 on failure. +.Pp +.Fn RSA_get_ex_data +returns the application data or +.Dv NULL +on failure. +.Dv NULL +may also be valid application data, but currently it can only fail if +given an invalid +.Fa idx +parameter. +.Pp +.Fa new_func +and +.Fa dup_func +should return 0 for failure and 1 for success. +.Pp +On failure an error code can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr CRYPTO_set_ex_data 3 , +.Xr rsa 3 +.Sh HISTORY +.Fn RSA_get_ex_new_index , +.Fn RSA_set_ex_data , +and +.Fn RSA_get_ex_data +are available since SSLeay 0.9.0. +.Sh BUGS +.Fa dup_func +is currently never called. +.Pp +The return value of +.Fa new_func +is ignored. +.Pp +The +.Fa new_func +function isn't very useful because no meaningful values are present in +the parent RSA structure when it is called. diff --git a/src/lib/libcrypto/man/RSA_new.3 b/src/lib/libcrypto/man/RSA_new.3 new file mode 100644 index 0000000000..b01c8cd089 --- /dev/null +++ b/src/lib/libcrypto/man/RSA_new.3 @@ -0,0 +1,46 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt RSA_NEW 3 +.Os +.Sh NAME +.Nm RSA_new , +.Nm RSA_free +.Nd allocate and free RSA objects +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft RSA * +.Fn RSA_new void +.Ft void +.Fo RSA_free +.Fa "RSA *rsa" +.Fc +.Sh DESCRIPTION +.Fn RSA_new +allocates and initializes an +.Vt RSA +structure. +It is equivalent to calling +.Fn RSA_new_method NULL . +.Pp +.Fn RSA_free +frees the +.Vt RSA +structure and its components. +The key is erased before the memory is returned to the system. +.Sh RETURN VALUES +If the allocation fails, +.Fn RSA_new +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 . +Otherwise it returns a pointer to the newly allocated structure. +.Sh SEE ALSO +.Xr ERR_get_error 3 , +.Xr rsa 3 , +.Xr RSA_generate_key 3 , +.Xr RSA_new_method 3 +.Sh HISTORY +.Fn RSA_new +and +.Fn RSA_free +are available in all versions of SSLeay and OpenSSL. diff --git a/src/lib/libcrypto/man/RSA_padding_add_PKCS1_type_1.3 b/src/lib/libcrypto/man/RSA_padding_add_PKCS1_type_1.3 new file mode 100644 index 0000000000..7724f45970 --- /dev/null +++ b/src/lib/libcrypto/man/RSA_padding_add_PKCS1_type_1.3 @@ -0,0 +1,197 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt RSA_PADDING_ADD_PKCS1_TYPE_1 3 +.Os +.Sh NAME +.Nm RSA_padding_add_PKCS1_type_1 , +.Nm RSA_padding_check_PKCS1_type_1 , +.Nm RSA_padding_add_PKCS1_type_2 , +.Nm RSA_padding_check_PKCS1_type_2 , +.Nm RSA_padding_add_PKCS1_OAEP , +.Nm RSA_padding_check_PKCS1_OAEP , +.Nm RSA_padding_add_SSLv23 , +.Nm RSA_padding_check_SSLv23 , +.Nm RSA_padding_add_none , +.Nm RSA_padding_check_none +.Nd asymmetric encryption padding +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft int +.Fo RSA_padding_add_PKCS1_type_1 +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fc +.Ft int +.Fo RSA_padding_check_PKCS1_type_1 +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fa "int rsa_len" +.Fc +.Ft int +.Fo RSA_padding_add_PKCS1_type_2 +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fc +.Ft int +.Fo RSA_padding_check_PKCS1_type_2 +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fa "int rsa_len" +.Fc +.Ft int +.Fo RSA_padding_add_PKCS1_OAEP +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fa "unsigned char *p" +.Fa "int pl" +.Fc +.Ft int +.Fo RSA_padding_check_PKCS1_OAEP +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fa "int rsa_len" +.Fa "unsigned char *p" +.Fa "int pl" +.Fc +.Ft int +.Fo RSA_padding_add_SSLv23 +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fc +.Ft int +.Fo RSA_padding_check_SSLv23 +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fa "int rsa_len" +.Fc +.Ft int +.Fo RSA_padding_add_none +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fc +.Ft int +.Fo RSA_padding_check_none +.Fa "unsigned char *to" +.Fa "int tlen" +.Fa "unsigned char *f" +.Fa "int fl" +.Fa "int rsa_len" +.Fc +.Sh DESCRIPTION +These functions are called from the RSA encrypt, decrypt, sign, and +verify functions. +Normally they should not be called from application programs. +.Pp +However, they can also be called directly to implement padding for other +asymmetric ciphers. +.Fn RSA_padding_add_PKCS1_OAEP +and +.Fn RSA_padding_check_PKCS1_OAEP +may be used in an application combined with +.Dv RSA_NO_PADDING +in order to implement OAEP with an encoding parameter. +.Pp +.Fn RSA_padding_add_* +encodes +.Fa fl +bytes from +.Fa f +so as to fit into +.Fa tlen +bytes and stores the result at +.Fa to . +An error occurs if +.Fa fl +does not meet the size requirements of the encoding method. +.Pp +The following encoding methods are implemented: +.Pp +.Bl -tag -width PKCS1_type_2 -compact +.It PKCS1_type_1 +PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); +used for signatures +.It PKCS1_type_2 +PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2) +.It PKCS1_OAEP +PKCS #1 v2.0 EME-OAEP +.It SSLv23 +PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification +.It none +simply copy the data +.El +.Pp +.Fn RSA_padding_check_* +verifies that the +.Fa fl +bytes at +.Fa f +contain a valid encoding for a +.Fa rsa_len +byte RSA key in the respective encoding method and stores the recovered +data of at most +.Fa tlen +bytes (for +.Dv RSA_NO_PADDING : +of size +.Fa tlen ) +at +.Fa to . +.Pp +For +.Fn RSA_padding_*_OAEP , +.Fa p +points to the encoding parameter of length +.Fa pl . +.Fa p +may be +.Dv NULL +if +.Fa pl +is 0. +.Sh RETURN VALUES +The +.Fn RSA_padding_add_* +functions return 1 on success or 0 on error. +The +.Fn RSA_padding_check_* +functions return the length of the recovered data or -1 on error. +Error codes can be obtained by calling +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr RSA_private_decrypt 3 , +.Xr RSA_public_encrypt 3 , +.Xr RSA_sign 3 , +.Xr RSA_verify 3 +.Sh HISTORY +.Fn RSA_padding_add_PKCS1_type_1 , +.Fn RSA_padding_check_PKCS1_type_1 , +.Fn RSA_padding_add_PKCS1_type_2 , +.Fn RSA_padding_check_PKCS1_type_2 , +.Fn RSA_padding_add_SSLv23 , +.Fn RSA_padding_check_SSLv23 , +.Fn RSA_padding_add_none , +and +.Fn RSA_padding_check_none +appeared in SSLeay 0.9.0. +.Pp +.Fn RSA_padding_add_PKCS1_OAEP +and +.Fn RSA_padding_check_PKCS1_OAEP +were added in OpenSSL 0.9.2b. diff --git a/src/lib/libcrypto/man/RSA_print.3 b/src/lib/libcrypto/man/RSA_print.3 new file mode 100644 index 0000000000..986dce2eb4 --- /dev/null +++ b/src/lib/libcrypto/man/RSA_print.3 @@ -0,0 +1,91 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt RSA_PRINT 3 +.Os +.Sh NAME +.Nm RSA_print , +.Nm RSA_print_fp , +.Nm DSAparams_print , +.Nm DSAparams_print_fp , +.Nm DSA_print , +.Nm DSA_print_fp , +.Nm DHparams_print , +.Nm DHparams_print_fp +.Nd print cryptographic parameters +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft int +.Fo RSA_print +.Fa "BIO *bp" +.Fa "RSA *x" +.Fa "int offset" +.Fc +.Ft int +.Fo RSA_print_fp +.Fa "FILE *fp" +.Fa "RSA *x" +.Fa "int offset" +.Fc +.In openssl/dsa.h +.Ft int +.Fo DSAparams_print +.Fa "BIO *bp" +.Fa "DSA *x" +.Fc +.Ft int +.Fo DSAparams_print_fp +.Fa "FILE *fp" +.Fa "DSA *x" +.Fc +.Ft int +.Fo DSA_print +.Fa "BIO *bp" +.Fa "DSA *x" +.Fa "int offset" +.Fc +.Ft int +.Fo DSA_print_fp +.Fa "FILE *fp" +.Fa "DSA *x" +.Fa "int offset" +.Fc +.In openssl/dh.h +.Ft int +.Fo DHparams_print +.Fa "BIO *bp" +.Fa "DH *x" +.Fc +.Ft int +.Fo DHparams_print_fp +.Fa "FILE *fp" +.Fa "DH *x" +.Fc +.Sh DESCRIPTION +A human-readable hexadecimal output of the components of the RSA key, +DSA parameters or key or DH parameters is printed to +.Fa bp +or +.Fa fp . +.Pp +The output lines are indented by +.Fa offset +spaces. +.Sh RETURN VALUES +These functions return 1 on success or 0 on error. +.Sh SEE ALSO +.Xr BN_bn2bin 3 , +.Xr dh 3 , +.Xr dsa 3 , +.Xr rsa 3 +.Sh HISTORY +.Fn RSA_print , +.Fn RSA_print_fp , +.Fn DSA_print , +.Fn DSA_print_fp , +.Fn DHparams_print , +and +.Fn DHparams_print_fp +are available in all versions of SSLeay and OpenSSL. +.Fn DSAparams_print +and +.Fn DSAparams_print_fp +were added in SSLeay 0.8. diff --git a/src/lib/libcrypto/man/RSA_private_encrypt.3 b/src/lib/libcrypto/man/RSA_private_encrypt.3 new file mode 100644 index 0000000000..ff59e66f6a --- /dev/null +++ b/src/lib/libcrypto/man/RSA_private_encrypt.3 @@ -0,0 +1,97 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt RSA_PRIVATE_ENCRYPT 3 +.Os +.Sh NAME +.Nm RSA_private_encrypt , +.Nm RSA_public_decrypt +.Nd low level signature operations +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft int +.Fo RSA_private_encrypt +.Fa "int flen" +.Fa "unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Ft int +.Fo RSA_public_decrypt +.Fa "int flen" +.Fa "unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Sh DESCRIPTION +These functions handle RSA signatures at a low level. +.Pp +.Fn RSA_private_encrypt +signs the +.Fa flen +bytes at +.Fa from +(usually a message digest with an algorithm identifier) using the +private key +.Fa rsa +and stores the signature in +.Fa to . +.Fa to +must point to +.Fn RSA_size rsa +bytes of memory. +.Pp +.Fa padding +denotes one of the following modes: +.Bl -tag -width Ds +.It Dv RSA_PKCS1_PADDING +PKCS #1 v1.5 padding. +This function does not handle the +.Sy algorithmIdentifier +specified in PKCS #1. +When generating or verifying PKCS #1 signatures, +.Xr RSA_sign 3 +and +.Xr RSA_verify 3 +should be used. +.It Dv RSA_NO_PADDING +Raw RSA signature. +This mode should only be used to implement cryptographically sound +padding modes in the application code. +Signing user data directly with RSA is insecure. +.El +.Pp +.Fn RSA_public_decrypt +recovers the message digest from the +.Fa flen +bytes long signature at +.Fa from +using the signer's public key +.Fa rsa . +.Fa to +must point to a memory section large enough to hold the message digest +(which is smaller than +.Fn RSA_size rsa +- 11). +.Fa padding +is the padding mode that was used to sign the data. +.Sh RETURN VALUES +.Fn RSA_private_encrypt +returns the size of the signature (i.e., +.Fn RSA_size rsa ) . +.Fn RSA_public_decrypt +returns the size of the recovered message digest. +.Pp +On error, -1 is returned; the error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ERR_get_error 3 , +.Xr rsa 3 , +.Xr RSA_sign 3 , +.Xr RSA_verify 3 +.Sh HISTORY +The +.Fa padding +argument was added in SSLeay 0.8. +.Dv RSA_NO_PADDING +is available since SSLeay 0.9.0. diff --git a/src/lib/libcrypto/man/RSA_public_encrypt.3 b/src/lib/libcrypto/man/RSA_public_encrypt.3 new file mode 100644 index 0000000000..c2c81019c6 --- /dev/null +++ b/src/lib/libcrypto/man/RSA_public_encrypt.3 @@ -0,0 +1,108 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt RSA_PUBLIC_ENCRYPT 3 +.Os +.Sh NAME +.Nm RSA_public_encrypt , +.Nm RSA_private_decrypt +.Nd RSA public key cryptography +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft int +.Fo RSA_public_encrypt +.Fa "int flen" +.Fa "unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Ft int +.Fo RSA_private_decrypt +.Fa "int flen" +.Fa "unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Sh DESCRIPTION +.Fn RSA_public_encrypt +encrypts the +.Fa flen +bytes at +.Fa from +(usually a session key) using the public key +.Fa rsa +and stores the ciphertext in +.Fa to . +.Fa to +must point to +.Fn RSA_size rsa +bytes of memory. +.Pp +.Fa padding +denotes one of the following modes: +.Bl -tag -width Ds +.It Dv RSA_PKCS1_PADDING +PKCS #1 v1.5 padding. +This currently is the most widely used mode. +.It Dv RSA_PKCS1_OAEP_PADDING +EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty +encoding parameter. +This mode is recommended for all new applications. +.It Dv RSA_SSLV23_PADDING +PKCS #1 v1.5 padding with an SSL-specific modification that denotes that +the server is SSL3 capable. +.It Dv RSA_NO_PADDING +Raw RSA encryption. +This mode should only be used to implement cryptographically sound +padding modes in the application code. +Encrypting user data directly with RSA is insecure. +.El +.Pp +.Fa flen +must be less than +.Fn RSA_size rsa +- 11 for the PKCS #1 v1.5 based padding modes, less than +.Fn RSA_size rsa +- 41 for +.Dv RSA_PKCS1_OAEP_PADDING +and exactly +.Fn RSA_size rsa +for +.Dv RSA_NO_PADDING . +.Pp +.Fn RSA_private_decrypt +decrypts the +.Fa flen +bytes at +.Fa from +using the private key +.Fa rsa +and stores the plaintext in +.Fa to . +.Fa to +must point to a memory section large enough to hold the decrypted data +(which is smaller than +.Fn RSA_size rsa ) . +.Fa padding +is the padding mode that was used to encrypt the data. +.Sh RETURN VALUES +.Fn RSA_public_encrypt +returns the size of the encrypted data (i.e., +.Fn RSA_size rsa ) . +.Fn RSA_private_decrypt +returns the size of the recovered plaintext. +.Pp +On error, -1 is returned; the error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ERR_get_error 3 , +.Xr rsa 3 , +.Xr RSA_size 3 +.Sh STANDARDS +SSL, PKCS #1 v2.0 +.Sh HISTORY +The +.Fa padding +argument was added in SSLeay 0.8. +.Dv RSA_NO_PADDING is available since SSLeay 0.9.0. +OAEP was added in OpenSSL 0.9.2b. diff --git a/src/lib/libcrypto/man/RSA_set_method.3 b/src/lib/libcrypto/man/RSA_set_method.3 new file mode 100644 index 0000000000..d7a2756b70 --- /dev/null +++ b/src/lib/libcrypto/man/RSA_set_method.3 @@ -0,0 +1,339 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt RSA_SET_METHOD 3 +.Os +.Sh NAME +.Nm RSA_set_default_method , +.Nm RSA_get_default_method , +.Nm RSA_set_method , +.Nm RSA_get_method , +.Nm RSA_PKCS1_SSLeay , +.Nm RSA_null_method , +.Nm RSA_flags , +.Nm RSA_new_method , +.Nm RSA_get_default_openssl_method , +.Nm RSA_set_default_openssl_method +.Nd select RSA method +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft void +.Fo RSA_set_default_method +.Fa "const RSA_METHOD *meth" +.Fc +.Ft RSA_METHOD * +.Fn RSA_get_default_method void +.Ft int +.Fo RSA_set_method +.Fa "RSA *rsa" +.Fa "const RSA_METHOD *meth" +.Fc +.Ft RSA_METHOD * +.Fo RSA_get_method +.Fa "const RSA *rsa" +.Fc +.Ft RSA_METHOD * +.Fn RSA_PKCS1_SSLeay void +.Ft RSA_METHOD * +.Fn RSA_null_method void +.Ft int +.Fo RSA_flags +.Fa "const RSA *rsa" +.Fc +.Ft RSA * +.Fo RSA_new_method +.Fa "RSA_METHOD *meth" +.Fc +.Sh DESCRIPTION +An +.Vt RSA_METHOD +specifies the functions that OpenSSL uses for RSA operations. +By modifying the method, alternative implementations such as hardware +accelerators may be used. +See the +.Sx CAVEATS +section for how these RSA API functions are affected by the use of +.Xr engine 3 +API calls. +.Pp +Initially, the default +.Vt RSA_METHOD +is the OpenSSL internal implementation, as returned by +.Fn RSA_PKCS1_SSLeay . +.Pp +.Fn RSA_set_default_method +makes +.Fa meth +the default method for all +.Vt RSA +structures created later. +.Sy NB : +This is true only whilst no +.Vt ENGINE +has been set as a default for RSA, so this function is no longer +recommended. +.Pp +.Fn RSA_get_default_method +returns a pointer to the current default +.Vt RSA_METHOD . +However, the meaningfulness of this result is dependent on whether +the +.Xr engine 3 +API is being used, so this function is no longer recommended. +.Pp +.Fn RSA_set_method +selects +.Fa meth +to perform all operations using the key +.Fa rsa . +This will replace the +.Vt RSA_METHOD +used by the RSA key, and if the previous method was supplied by an +.Vt ENGINE , +the handle to that +.Vt ENGINE +will be released during the change. +It is possible to have RSA keys that only work with certain +.Vt RSA_METHOD +implementations (eg. from an +.Vt ENGINE +module that supports embedded hardware-protected keys), +and in such cases attempting to change the +.Vt RSA_METHOD +for the key can have unexpected results. +.Pp +.Fn RSA_get_method +returns a pointer to the +.Vt RSA_METHOD +being used by +.Fa rsa . +This method may or may not be supplied by an +.Vt ENGINE +implementation, but if it is, the return value can only be guaranteed +to be valid as long as the RSA key itself is valid and does not +have its implementation changed by +.Fn RSA_set_method . +.Pp +.Fn RSA_flags +returns the flags that are set for the current +.Vt RSA_METHOD +of +.Fa rsa . +See the +.Sx BUGS +section. +.Pp +.Fn RSA_new_method +allocates and initializes an +.Vt RSA +structure so that +.Fa meth +will be used for the RSA operations. +If +.Sy engine +is NULL, the default ENGINE for RSA operations is used, and if no +default ENGINE is set, the RSA_METHOD controlled by +.Fn RSA_set_default_method +is used. +.Pp +.Fn RSA_flags +returns the +.Sy flags +that are set for +.Fa rsa Ns 's +current method. +.Pp +.Fn RSA_new_method +allocates and initializes an +.Vt RSA +structure so that +.Fa meth +will be used for the RSA operations. +If +.Fa meth +is +.Dv NULL , +the default method is used. +.Sh THE RSA_METHOD STRUCTURE +.Bd -literal +typedef struct rsa_meth_st +{ + /* name of the implementation */ + const char *name; + + /* encrypt */ + int (*rsa_pub_enc)(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + /* verify arbitrary data */ + int (*rsa_pub_dec)(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + /* sign arbitrary data */ + int (*rsa_priv_enc)(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + /* decrypt */ + int (*rsa_priv_dec)(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some + implementations) */ + int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa); + + /* compute r = a ^ p mod m (May be NULL for some implementations) */ + int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); + + /* called at RSA_new */ + int (*init)(RSA *rsa); + + /* called at RSA_free */ + int (*finish)(RSA *rsa); + + /* RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key + * operations, even if p,q,dmp1,dmq1,iqmp + * are NULL + * RSA_FLAG_SIGN_VER - enable rsa_sign and rsa_verify + * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match + */ + int flags; + + char *app_data; /* ?? */ + + /* sign. For backward compatibility, this is used only + * if (flags & RSA_FLAG_SIGN_VER) + */ + int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len, + unsigned char *sigret, unsigned int *siglen, RSA *rsa); + + /* verify. For backward compatibility, this is used only + * if (flags & RSA_FLAG_SIGN_VER) + */ + int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len, + unsigned char *sigbuf, unsigned int siglen, RSA *rsa); + +} RSA_METHOD; +.Ed +.Sh RETURN VALUES +.Fn RSA_PKCS1_SSLeay , +.Fn RSA_null_method , +.Fn RSA_get_default_method +and +.Fn RSA_get_method +return pointers to the respective +.Vt RSA_METHOD . +.Pp +.Fn RSA_set_method +returns a pointer to the old +.Vt RSA_METHOD +implementation that was replaced. +However, this return value should probably be ignored because if it was +supplied by an +.Vt ENGINE , +the pointer could be invalidated at any time if the +.Vt ENGINE +is unloaded. +In fact, it could be unloaded as a result of the +.Fn RSA_set_method +function releasing its handle to the +.Vt ENGINE . +For this reason, the return type may be replaced with a +.Vt void +declaration in a future release. +.Pp +.Fn RSA_new_method +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 +if the allocation fails. +Otherwise it returns a pointer to the newly allocated structure. +.Sh SEE ALSO +.Xr rsa 3 , +.Xr RSA_new 3 +.Sh HISTORY +.Fn RSA_new_method +and +.Fn RSA_set_default_method +appeared in SSLeay 0.8. +.Fn RSA_get_default_method , +.Fn RSA_set_method , +and +.Fn RSA_get_method +as well as the +.Fa rsa_sign +and +.Fa rsa_verify +components of +.Vt RSA_METHOD +were added in OpenSSL 0.9.4. +.Pp +.Fn RSA_set_default_openssl_method +and +.Fn RSA_get_default_openssl_method +replaced +.Fn RSA_set_default_method +and +.Fn RSA_get_default_method +respectively, and +.Fn RSA_set_method +and +.Fn RSA_new_method +were altered to use +.Vt ENGINE Ns s +rather than +.Vt RSA_METHOD Ns s +during development of the +.Xr engine 3 +version of OpenSSL 0.9.6. +For 0.9.7, the handling of defaults in the +.Xr engine 3 +API was restructured so that this change was reversed, and behaviour +of the other functions resembled more closely the previous behaviour. +The behaviour of defaults in the +.Xr engine 3 +API now transparently overrides the behaviour of defaults in the +RSA API without requiring changing these function prototypes. +.Sh CAVEATS +As of version 0.9.7, +.Vt RSA_METHOD +implementations are grouped together with other algorithmic APIs (eg.\& +.Vt DSA_METHOD , +.Vt EVP_CIPHER , +etc.) into +.Vt ENGINE +modules. +If a default +.Vt ENGINE +is specified for RSA functionality using an +.Xr engine 3 +API function, that will override any RSA defaults set using the RSA +API, ie.\& +.Fn RSA_set_default_method . +For this reason, the +.Xr engine 3 +API is the recommended way to control default implementations for +use in RSA and other cryptographic algorithms. +.Sh BUGS +The behaviour of +.Fn RSA_flags +is a mis-feature that is left as-is for now to avoid creating +compatibility problems. +RSA functionality, such as the encryption functions, are controlled by +the +.Fa flags +value in the +.Vt RSA +key itself, not by the +.Fa flags +value in the +.Vt RSA_METHOD +attached to the RSA key (which is what this function returns). +If the flags element of an +.Vt RSA +key is changed, the changes will be honoured by RSA functionality +but will not be reflected in the return value of the +.Fn RSA_flags +function - in effect +.Fn RSA_flags +behaves more like a RSA_default_flags() function, which does not +currently exist. diff --git a/src/lib/libcrypto/man/RSA_sign.3 b/src/lib/libcrypto/man/RSA_sign.3 new file mode 100644 index 0000000000..2b9e5eb6f1 --- /dev/null +++ b/src/lib/libcrypto/man/RSA_sign.3 @@ -0,0 +1,103 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt RSA_SIGN 3 +.Os +.Sh NAME +.Nm RSA_sign , +.Nm RSA_verify +.Nd RSA signatures +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft int +.Fo RSA_sign +.Fa "int type" +.Fa "const unsigned char *m" +.Fa "unsigned int m_len" +.Fa "unsigned char *sigret" +.Fa "unsigned int *siglen" +.Fa "RSA *rsa" +.Fc +.Ft int +.Fo RSA_verify +.Fa "int type" +.Fa "const unsigned char *m" +.Fa "unsigned int m_len" +.Fa "unsigned char *sigbuf" +.Fa "unsigned int siglen" +.Fa "RSA *rsa" +.Fc +.Sh DESCRIPTION +.Fn RSA_sign +signs the message digest +.Fa m +of size +.Fa m_len +using the private key +.Fa rsa +as specified in PKCS #1 v2.0. +It stores the signature in +.Fa sigret +and the signature size in +.Fa siglen . +.Fa sigret +must point to +.Fn RSA_size rsa +bytes of memory. +Note that PKCS #1 adds meta-data, placing limits on the size of the key +that can be used. +See +.Xr RSA_private_encrypt 3 +for lower-level operations. +.Pp +.Fa type +denotes the message digest algorithm that was used to generate +.Fa m . +It usually is one of +.Dv NID_sha1 , +.Dv NID_ripemd160 , +or +.Dv NID_md5 ; +see +.Xr OBJ_nid2obj 3 +for details. +If +.Fa type +is +.Sy NID_md5_sha1 , +an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding and +no algorithm identifier) is created. +.Pp +.Fn RSA_verify +verifies that the signature +.Fa sigbuf +of size +.Fa siglen +matches a given message digest +.Fa m +of size +.Fa m_len . +.Fa type +denotes the message digest algorithm that was used to generate the +signature. +.Fa rsa +is the signer's public key. +.Sh RETURN VALUES +.Fn RSA_sign +returns 1 on success or 0 otherwise. +.Fn RSA_verify +returns 1 on successful verification or 0 otherwise. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ERR_get_error 3 , +.Xr objects 3 , +.Xr rsa 3 , +.Xr RSA_private_encrypt 3 , +.Xr RSA_public_decrypt 3 +.Sh STANDARDS +SSL, PKCS #1 v2.0 +.Sh HISTORY +.Fn RSA_sign +and +.Fn RSA_verify +are available in all versions of SSLeay and OpenSSL. diff --git a/src/lib/libcrypto/man/RSA_sign_ASN1_OCTET_STRING.3 b/src/lib/libcrypto/man/RSA_sign_ASN1_OCTET_STRING.3 new file mode 100644 index 0000000000..7398a294c9 --- /dev/null +++ b/src/lib/libcrypto/man/RSA_sign_ASN1_OCTET_STRING.3 @@ -0,0 +1,81 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt RSA_SIGN_ASN1_OCTET_STRING 3 +.Os +.Sh NAME +.Nm RSA_sign_ASN1_OCTET_STRING , +.Nm RSA_verify_ASN1_OCTET_STRING +.Nd RSA signatures +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft int +.Fo RSA_sign_ASN1_OCTET_STRING +.Fa "int dummy" +.Fa "unsigned char *m" +.Fa "unsigned int m_len" +.Fa "unsigned char *sigret" +.Fa "unsigned int *siglen" +.Fa "RSA *rsa" +.Fc +.Ft int +.Fo RSA_verify_ASN1_OCTET_STRING +.Fa "int dummy" +.Fa "unsigned char *m" +.Fa "unsigned int m_len" +.Fa "unsigned char *sigbuf" +.Fa "unsigned int siglen" +.Fa "RSA *rsa" +.Fc +.Sh DESCRIPTION +.Fn RSA_sign_ASN1_OCTET_STRING +signs the octet string +.Fa m +of size +.Fa m_len +using the private key +.Fa rsa +represented in DER using PKCS #1 padding. +It stores the signature in +.Fa sigret +and the signature size in +.Fa siglen . +.Fa sigret +must point to +.Fn RSA_size rsa +bytes of memory. +.Pp +.Fa dummy +is ignored. +.Pp +.Fn RSA_verify_ASN1_OCTET_STRING +verifies that the signature +.Fa sigbuf +of size +.Fa siglen +is the DER representation of a given octet string +.Fa m +of size +.Fa m_len . +.Fa dummy +is ignored. +.Fa rsa +is the signer's public key. +.Sh RETURN VALUES +.Fn RSA_sign_ASN1_OCTET_STRING +returns 1 on success or 0 otherwise. +.Fn RSA_verify_ASN1_OCTET_STRING +returns 1 on successful verification or 0 otherwise. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ERR_get_error 3 , +.Xr rsa 3 , +.Xr RSA_sign 3 , +.Xr RSA_verify 3 +.Sh HISTORY +.Fn RSA_sign_ASN1_OCTET_STRING +and +.Fn RSA_verify_ASN1_OCTET_STRING +were added in SSLeay 0.8. +.Sh BUGS +These functions serve no recognizable purpose. diff --git a/src/lib/libcrypto/man/RSA_size.3 b/src/lib/libcrypto/man/RSA_size.3 new file mode 100644 index 0000000000..8b9a4d0552 --- /dev/null +++ b/src/lib/libcrypto/man/RSA_size.3 @@ -0,0 +1,27 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt RSA_SIZE 3 +.Os +.Sh NAME +.Nm RSA_size +.Nd get RSA modulus size +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft int +.Fo RSA_size +.Fa "const RSA *rsa" +.Fc +.Sh DESCRIPTION +This function returns the RSA modulus size in bytes. +It can be used to determine how much memory must be allocated for an RSA +encrypted value. +.Pp +.Fa rsa->n +must not be +.Dv NULL . +.Sh RETURN VALUE +The size in bytes. +.Sh SEE ALSO +.Xr rsa 3 +.Sh HISTORY +.Fn RSA_size +is available in all versions of SSLeay and OpenSSL. diff --git a/src/lib/libcrypto/man/d2i_RSAPublicKey.3 b/src/lib/libcrypto/man/d2i_RSAPublicKey.3 new file mode 100644 index 0000000000..b54487a621 --- /dev/null +++ b/src/lib/libcrypto/man/d2i_RSAPublicKey.3 @@ -0,0 +1,101 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt D2I_RSAPUBLICKEY 3 +.Os +.Sh NAME +.Nm d2i_RSAPublicKey , +.Nm i2d_RSAPublicKey , +.Nm d2i_RSAPrivateKey , +.Nm i2d_RSAPrivateKey , +.Nm d2i_RSA_PUBKEY , +.Nm i2d_RSA_PUBKEY , +.Nm i2d_Netscape_RSA , +.Nm d2i_Netscape_RSA +.Nd RSA public and private key encoding functions +.Sh SYNOPSIS +.In openssl/rsa.h +.In openssl/x509.h +.Ft RSA * +.Fo d2i_RSAPublicKey +.Fa "RSA **a" +.Fa "const unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_RSAPublicKey +.Fa "RSA *a" +.Fa "unsigned char **pp" +.Fc +.Ft RSA * +.Fo d2i_RSA_PUBKEY +.Fa "RSA **a" +.Fa "const unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_RSA_PUBKEY +.Fa "RSA *a" +.Fa "unsigned char **pp" +.Fc +.Ft RSA * +.Fo d2i_RSAPrivateKey +.Fa "RSA **a" +.Fa "const unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_RSAPrivateKey +.Fa "RSA *a" +.Fa "unsigned char **pp" +.Fc +.Ft int +.Fo i2d_Netscape_RSA +.Fa "RSA *a" +.Fa "unsigned char **pp" +.Fa "int (*cb)()" +.Fc +.Ft RSA * +.Fo d2i_Netscape_RSA +.Fa "RSA **a" +.Fa "const unsigned char **pp" +.Fa "long length" +.Fa "int (*cb)()" +.Fc +.Sh DESCRIPTION +.Fn d2i_RSAPublicKey +and +.Fn i2d_RSAPublicKey +decode and encode a PKCS#1 RSAPublicKey structure. +.Pp +.Fn d2i_RSA_PUBKEY +and +.Fn i2d_RSA_PUBKEY +decode and encode an RSA public key using a SubjectPublicKeyInfo +(certificate public key) structure. +.Pp +.Fn d2i_RSAPrivateKey , +.Fn i2d_RSAPrivateKey +decode and encode a PKCS#1 RSAPrivateKey structure. +.Pp +.Fn d2i_Netscape_RSA , +.Fn i2d_Netscape_RSA +decode and encode an RSA private key in NET format. +.Pp +The usage of all of these functions is similar to +.Xr d2i_X509 3 +and +.Xr i2d_X509 3 . +.Pp +The +.Vt RSA +structure passed to the private key encoding functions should have all +the PKCS#1 private key components present. +.Pp +The data encoded by the private key functions is unencrypted and +therefore offers no private key security. +.Pp +The NET format functions are present to provide compatibility with +certain very old software. +This format has some severe security weaknesses and should be avoided if +possible. +.Sh SEE ALSO +.Xr d2i_X509 3 diff --git a/src/lib/libcrypto/man/rsa.3 b/src/lib/libcrypto/man/rsa.3 new file mode 100644 index 0000000000..7c34f3595b --- /dev/null +++ b/src/lib/libcrypto/man/rsa.3 @@ -0,0 +1,238 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt RSA 3 +.Os +.Sh NAME +.Nm rsa +.Nd RSA public key cryptosystem +.Sh SYNOPSIS +.In openssl/rsa.h +.In openssl/engine.h +.Ft RSA * +.Fn RSA_new void +.Ft void +.Fo RSA_free +.Fa "RSA *rsa" +.Fc +.Ft int +.Fo RSA_public_encrypt +.Fa "int flen" +.Fa "unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Ft int +.Fo RSA_private_decrypt +.Fa "int flen" +.Fa "unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Ft int +.Fo RSA_private_encrypt +.Fa "int flen" +.Fa "unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Ft int +.Fo RSA_public_decrypt +.Fa "int flen" +.Fa "unsigned char *from" +.Fa "unsigned char *to" +.Fa "RSA *rsa" +.Fa "int padding" +.Fc +.Ft int +.Fo RSA_sign +.Fa "int type" +.Fa "unsigned char *m" +.Fa "unsigned int m_len" +.Fa "unsigned char *sigret" +.Fa "unsigned int *siglen" +.Fa "RSA *rsa" +.Fc +.Ft int +.Fo RSA_verify +.Fa "int type" +.Fa "unsigned char *m" +.Fa "unsigned int m_len" +.Fa "unsigned char *sigbuf" +.Fa "unsigned int siglen" +.Fa "RSA *rsa" +.Fc +.Ft int +.Fo RSA_size +.Fa "const RSA *rsa" +.Fc +.Ft RSA * +.Fo RSA_generate_key +.Fa "int num" +.Fa "unsigned long e" +.Fa "void (*callback)(int, int, void *)" +.Fa "void *cb_arg" +.Fc +.Ft int +.Fo RSA_check_key +.Fa "RSA *rsa" +.Fc +.Ft int +.Fo RSA_blinding_on +.Fa "RSA *rsa" +.Fa "BN_CTX *ctx" +.Fc +.Ft void +.Fo RSA_blinding_off +.Fa "RSA *rsa" +.Fc +.Ft void +.Fo RSA_set_default_method +.Fa "const RSA_METHOD *meth" +.Fc +.Ft const RSA_METHOD * +.Fn RSA_get_default_method void +.Ft int +.Fo RSA_set_method +.Fa "RSA *rsa" +.Fa "const RSA_METHOD *meth" +.Fc +.Ft const RSA_METHOD * +.Fo RSA_get_method +.Fa "const RSA *rsa" +.Fc +.Ft RSA_METHOD * +.Fn RSA_PKCS1_SSLeay void +.Ft RSA_METHOD * +.Fn RSA_null_method void +.Ft int +.Fo RSA_flags +.Fa "const RSA *rsa" +.Fc +.Ft RSA * +.Fo RSA_new_method +.Fa "ENGINE *engine" +.Fc +.Ft int +.Fo RSA_print +.Fa "BIO *bp" +.Fa "RSA *x" +.Fa "int offset" +.Fc +.Ft int +.Fo RSA_print_fp +.Fa "FILE *fp" +.Fa "RSA *x" +.Fa "int offset" +.Fc +.Ft int +.Fo RSA_get_ex_new_index +.Fa "long argl" +.Fa "char *argp" +.Fa "int (*new_func)()" +.Fa "int (*dup_func)()" +.Fa "void (*free_func)()" +.Fc +.Ft int +.Fo RSA_set_ex_data +.Fa "RSA *r" +.Fa "int idx" +.Fa "char *arg" +.Fc +.Ft char * +.Fo RSA_get_ex_data +.Fa "RSA *r" +.Fa "int idx" +.Fc +.Ft int +.Fo RSA_sign_ASN1_OCTET_STRING +.Fa "int dummy" +.Fa "unsigned char *m" +.Fa "unsigned int m_len" +.Fa "unsigned char *sigret" +.Fa "unsigned int *siglen" +.Fa "RSA *rsa" +.Fc +.Ft int +.Fo RSA_verify_ASN1_OCTET_STRING +.Fa "int dummy" +.Fa "unsigned char *m" +.Fa "unsigned int m_len" +.Fa "unsigned char *sigbuf" +.Fa "unsigned int siglen" +.Fa "RSA *rsa" +.Fc +.Sh DESCRIPTION +These functions implement RSA public key encryption and signatures as +defined in PKCS #1 v2.0 [RFC 2437]. +.Pp +The +.Vt RSA +structure consists of several BIGNUM components. +It can contain public as well as private RSA keys: +.Bd -literal +typdef struct { + BIGNUM *n; // public modulus + BIGNUM *e; // public exponent + BIGNUM *d; // private exponent + BIGNUM *p; // secret prime factor + BIGNUM *q; // secret prime factor + BIGNUM *dmp1; // d mod (p-1) + BIGNUM *dmq1; // d mod (q-1) + BIGNUM *iqmp; // q^-1 mod p + // ... +} RSA; +.Ed +.Pp +In public keys, the private exponent and the related secret values are +.Dv NULL . +.Pp +.Fa p , +.Fa q , +.Fa dmp1 , +.Fa dmq1 , +and +.Fa iqmp +may be +.Dv NULL +in private keys, but the RSA operations are much faster when these +values are available. +.Pp +Note that RSA keys may use non-standard +.Vt RSA_METHOD +implementations, either directly or by the use of +.Vt ENGINE +modules. +In some cases (eg. an +.Vt ENGINE +providing support for hardware-embedded keys), these +.Vt BIGNUM +values will not be used by the implementation or may be used for +alternative data storage. +For this reason, applications should generally avoid using +.Vt RSA +structure elements directly and instead use API functions to query +or modify keys. +.Sh SEE ALSO +.Xr bn 3 , +.Xr dh 3 , +.Xr dsa 3 , +.Xr engine 3 , +.Xr RSA_blinding_on 3 , +.Xr RSA_check_key 3 , +.Xr RSA_generate_key 3 , +.Xr RSA_get_ex_new_index 3 , +.Xr RSA_new 3 , +.Xr RSA_padding_add_PKCS1_type_1 3 , +.Xr RSA_print 3 , +.Xr RSA_private_encrypt 3 , +.Xr RSA_public_encrypt 3 , +.Xr RSA_set_method 3 , +.Xr RSA_sign 3 , +.Xr RSA_sign_ASN1_OCTET_STRING 3 , +.Xr RSA_size 3 +.Sh STANDARDS +SSL, PKCS #1 v2.0 +.Pp +RSA was covered by a US patent which expired in September 2000. -- cgit v1.2.3-55-g6feb