Document the RSA library.
authorUlf Möller <ulf@openssl.org>
Tue, 11 Jan 2000 22:35:21 +0000 (22:35 +0000)
committerUlf Möller <ulf@openssl.org>
Tue, 11 Jan 2000 22:35:21 +0000 (22:35 +0000)
17 files changed:
Makefile.org
doc/crypto/RSA_blinding_on.pod [new file with mode: 0644]
doc/crypto/RSA_check_key.pod [new file with mode: 0644]
doc/crypto/RSA_generate_key.pod [new file with mode: 0644]
doc/crypto/RSA_get_ex_new_index.pod [new file with mode: 0644]
doc/crypto/RSA_new.pod [new file with mode: 0644]
doc/crypto/RSA_padding_add_PKCS1_type_1.pod [new file with mode: 0644]
doc/crypto/RSA_print.pod [new file with mode: 0644]
doc/crypto/RSA_private_encrypt.pod [new file with mode: 0644]
doc/crypto/RSA_public_encrypt.pod [new file with mode: 0644]
doc/crypto/RSA_set_method.pod [new file with mode: 0644]
doc/crypto/RSA_sign.pod [new file with mode: 0644]
doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod [new file with mode: 0644]
doc/crypto/RSA_size.pod [new file with mode: 0644]
doc/crypto/crypto.pod [new file with mode: 0644]
doc/crypto/d2i_RSAPublicKey.pod [new file with mode: 0644]
doc/crypto/rsa.pod [new file with mode: 0644]

index 47fadd2..e4729ca 100644 (file)
@@ -354,14 +354,8 @@ install: all
                chmod 644 $(INSTALL_PREFIX)$(INSTALLTOP)/lib/$$i ); \
        done
        @echo installing man 1
-       @for i in doc/man/*.pod ; \
-       do pod2man --section=1 --date=`date +%Y-%m-%d` --center=OpenSSL \
-                --release=$(VERSION) $$i > $(INSTALL_PREFIX)$(INSTALLTOP)/man/man1/`basename $$i .pod`.1; \
-       done
+       @for i in doc/man/*.pod; do (cd `dirname $$i`; pod2man --section=1 --date=`date +%Y-%m-%d` --center=OpenSSL --release=$(VERSION) `basename $$i` >  $(INSTALL_PREFIX)$(INSTALLTOP)/man/man1/`basename $$i .pod`.1); done
        @echo installing man 3
-       @for i in doc/crypto.pod doc/ssl.pod ; \
-       do pod2man --section=3 --date=`date +%Y-%m-%d` --center=OpenSSL \
-                --release=$(VERSION) $$i > $(INSTALL_PREFIX)$(INSTALLTOP)/man/man3/`basename $$i .pod`.3; \
-       done
+       @for i in doc/crypto/*.pod doc/ssl.pod; do (cd `dirname $$i`; pod2man --section=3 --date=`date +%Y-%m-%d` --center=OpenSSL --release=$(VERSION) `basename $$i` >  $(INSTALL_PREFIX)$(INSTALLTOP)/man/man3/`basename $$i .pod`.3); done
 
 # DO NOT DELETE THIS LINE -- make depend depends on it.
diff --git a/doc/crypto/RSA_blinding_on.pod b/doc/crypto/RSA_blinding_on.pod
new file mode 100644 (file)
index 0000000..41707df
--- /dev/null
@@ -0,0 +1,43 @@
+=pod
+
+=head1 NAME
+
+RSA_blinding_on, RSA_blinding_off - Protect the RSA operation from timing attacks
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_blinding_on(RSA *rsa, BN_CTX *ctx);
+
+ void RSA_blinding_off(RSA *rsa);
+
+=head1 DESCRIPTION
+
+RSA is vulnerable from 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<rsa> and generates a
+random blinding factor. B<ctx> is B<NULL> or a pre-allocated and
+initialized B<BN_CTX>. The random number generator must be seeded
+prior to calling RSA_blinding_on().
+
+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.
+
+RSA_blinding_off() returns no value.
+
+=head1 SEE ALSO
+
+rsa(3), rand(3)
+
+=head1 HISTORY
+
+RSA_blinding_on() and RSA_blinding_off() appeared in SSLeay 0.9.0.
+
+=cut
diff --git a/doc/crypto/RSA_check_key.pod b/doc/crypto/RSA_check_key.pod
new file mode 100644 (file)
index 0000000..c1b9507
--- /dev/null
@@ -0,0 +1,39 @@
+=pod
+
+=head1 NAME
+
+RSA_check_key - Validate RSA keys
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_check_key(RSA *rsa);
+
+=head1 DESCRIPTION
+
+This function validates RSA keys. It checks that B<p> and B<q> are
+in fact prime, and that B<n = p*q>.
+
+In the case of private keys, it also checks that B<d*e = 1 mod (p-1*q-1)>,
+and that B<dmp1>, B<dmq1> and B<iqmp> are set correctly or are B<NULL>.
+
+The key's public components may not be B<NULL>.
+
+=head1 RETURN VALUE
+
+RSA_check_key() returns 1 if B<rsa> 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 ERR_get_error(3).
+
+=head1 SEE ALSO
+
+rsa(3), err(3)
+
+=head1 HISTORY
+
+RSA_check() appeared in OpenSSL 0.9.4.
+
+=cut
diff --git a/doc/crypto/RSA_generate_key.pod b/doc/crypto/RSA_generate_key.pod
new file mode 100644 (file)
index 0000000..cdf5270
--- /dev/null
@@ -0,0 +1,68 @@
+=pod
+
+=head1 NAME
+
+RSA_generate_key - Generate RSA key pair
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ RSA *RSA_generate_key(int num, unsigned long e,
+    void (*callback)(int,int,void *), void *cb_arg);
+
+=head1 DESCRIPTION
+
+RSA_generate_key() generates a key pair and returns it in a newly
+allocated B<RSA> structure. The pseudo-random number generator must
+be seeded prior to calling RSA_generate_key().
+
+The modulus size will be B<num> bits, and the public exponent will be
+B<e>. Key sizes with B<num> E<lt> 1024 should be considered insecure.
+The exponent is an odd number, typically 3 or 65535.
+
+A callback function may be used to provide feedback about the
+progress of the key generation. If B<callback> is not B<NULL>, it
+will be called as follows:
+
+=over 4
+
+=item *
+
+While a random prime number is generated, it is called as
+described in L<BN_generate_prime(3)>.
+
+=item *
+
+When the n-th randomly generated prime is rejected as not
+suitable for the key, B<callback(2, n, cb_arg)> is called.
+
+=item *
+
+When a random p has been found with p-1 relatively prime to B<e>,
+it is called as B<callback(3, 0, cb_arg)>.
+
+=back
+
+The process is then repeated for prime q with B<callback(3, 1, cb_arg)>.
+
+=head1 RETURN VALUES
+
+If key generation fails, RSA_generate_key() returns B<NULL>; the
+error codes can be obtained by ERR_get_error(3).
+
+=head1 BUGS
+
+B<callback(2, x, cb_arg)> is used with two different meanings.
+
+RSA_generate_key() goes into an infinite loop for illegal input values.
+
+=head1 SEE ALSO
+
+err(3), rand(3), rsa(3), RSA_free(3)
+
+=head1 HISTORY
+
+The B<cb_arg> argument was added in SSLeay 0.9.0.
+
+=cut
diff --git a/doc/crypto/RSA_get_ex_new_index.pod b/doc/crypto/RSA_get_ex_new_index.pod
new file mode 100644 (file)
index 0000000..2afcc20
--- /dev/null
@@ -0,0 +1,34 @@
+=pod
+
+=head1 NAME
+
+RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - ...
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ 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);
+
+=head1 DESCRIPTION
+
+...
+
+=head1 RETURN VALUES
+
+...
+
+=head1 SEE ALSO
+
+...
+
+=head1 HISTORY
+
+...
+
+=cut
diff --git a/doc/crypto/RSA_new.pod b/doc/crypto/RSA_new.pod
new file mode 100644 (file)
index 0000000..a5df377
--- /dev/null
@@ -0,0 +1,38 @@
+=pod
+
+=head1 NAME
+
+RSA_new, RSA_free - allocate and free RSA objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ RSA * RSA_new(void);
+
+ void RSA_free(RSA *rsa);
+
+=head1 DESCRIPTION
+
+RSA_new() allocates and initializes an B<RSA> structure.
+
+RSA_free() frees the B<RSA> structure and its components. The key is
+erased before the memory is erased returned to the system.
+
+=head1 RETURN VALUES
+
+If the allocation fails, RSA_new() returns B<NULL> and sets an error
+code that can be obtained by ERR_get_error(3). Otherwise it returns
+a pointer to the newly allocated structure.
+
+RSA_free() returns no value.
+
+=head1 SEE ALSO
+
+err(3), rsa(3), RSA_generate_key(3)
+
+=head1 HISTORY
+
+RSA_new() and RSA_free() are available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/RSA_padding_add_PKCS1_type_1.pod b/doc/crypto/RSA_padding_add_PKCS1_type_1.pod
new file mode 100644 (file)
index 0000000..564ac02
--- /dev/null
@@ -0,0 +1,120 @@
+=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 <openssl/rsa.h>
+
+ 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.
+
+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<RSA_NO_PADDING> in order to implement OAEP with an encoding
+parameter.
+
+RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into
+B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl>
+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 EME-OAEP
+
+=item SSLv23
+
+PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification
+
+=item none
+
+simply copy the data
+
+=back
+
+The random number generator must be seeded prior to calling
+RSA_padding_add_xxx().
+
+RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain
+a valid encoding for a B<rsa_len> byte RSA key in the respective
+encoding method and stores the recovered data of at most B<tlen> bytes
+at B<to>.
+
+For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter
+of length B<pl>. B<p> may be B<NULL> if B<pl> 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
+ERR_get_error(3).
+
+=head1 SEE ALSO
+
+RSA_public_encrypt(3), RSA_private_decrypt(3), RSA_sign(3), RSA_verify(3)
+
+=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/doc/crypto/RSA_print.pod b/doc/crypto/RSA_print.pod
new file mode 100644 (file)
index 0000000..2361daa
--- /dev/null
@@ -0,0 +1,31 @@
+=pod
+
+=head1 NAME
+
+RSA_print, RSA_print_fp - Print RSA key
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_print(BIO *bp, RSA *x, int offset);
+
+ int RSA_print_fp(FILE *fp, RSA *x, int offset);
+
+=head1 DESCRIPTION
+
+...
+
+=head1 RETURN VALUES
+
+...
+
+=head1 SEE ALSO
+
+...
+
+=head1 HISTORY
+
+...
+
+=cut
diff --git a/doc/crypto/RSA_private_encrypt.pod b/doc/crypto/RSA_private_encrypt.pod
new file mode 100644 (file)
index 0000000..59ab49d
--- /dev/null
@@ -0,0 +1,72 @@
+=pod
+
+=head1 NAME
+
+RSA_private_encrypt, RSA_public_decrypt - Low level signature operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ 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<flen> bytes at B<from> (usually a
+message digest with an algorithm identifier) using the private key
+B<rsa> and stores the signature in B<to>. B<to> must point to
+B<RSA_size(rsa)> bytes of memory.
+
+B<padding> denotes one of the following modes:
+
+=over 4
+
+=item RSA_PKCS1_PADDING
+
+PKCS #1 v1.5 padding. This function does not handle the
+B<algorithmIdentifier> specified in PKCS #1. When generating or
+verifying PKCS #1 signatures, RSA_sign(3) and RSA_verify(3) should be
+used.
+
+=item RSA_NO_PADDING
+
+Raw RSA signature. This mode should I<only> be used to implement
+cryptographically sound padding modes in the application code.
+Signing user data directly with RSA is insecure.
+
+=back
+
+The random number generator must be seeded prior to calling
+RSA_private_encrypt().
+
+RSA_public_decrypt() recovers the message digest from the B<flen>
+bytes long signature at B<from> using the signer's public key
+B<rsa>. B<to> must point to a memory section large enough to hold the
+message digest (which is smaller than B<RSA_size(rsa) -
+11>). B<padding> 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 ERR_get_error(3).
+
+=head1 SEE ALSO
+
+err(3), rand(3), rsa(3), RSA_sign(3), RSA_verify(3)
+
+=head1 HISTORY
+
+The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is
+available since SSLeay 0.9.0.
+
+=cut
diff --git a/doc/crypto/RSA_public_encrypt.pod b/doc/crypto/RSA_public_encrypt.pod
new file mode 100644 (file)
index 0000000..a7b51e9
--- /dev/null
@@ -0,0 +1,86 @@
+=pod
+
+=head1 NAME
+
+RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ 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<flen> bytes at B<from> (usually a
+session key) using the public key B<rsa> and stores the ciphertext in
+B<to>. B<to> must point to B<RSA_size(rsa)> bytes of memory.
+
+B<padding> 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<only> be used to implement
+cryptographically sound padding modes in the application code.
+Encrypting user data directly with RSA is insecure.
+
+=back
+
+B<flen> must be less than RSA_size(rsa) - 11 for the PKCS #1 v1.5
+based padding modes, and less than RSA_size(rsa) - 21 for
+RSA_PKCS1_OAEP_PADDING. The random number generator must be seeded
+prior to calling RSA_public_encrypt().
+
+RSA_private_decrypt() decrypts the B<flen> bytes at B<from> using the
+private key B<rsa> and stores the plaintext in B<to>. B<to> must point
+to a memory section large enough to hold the decrypted data (which is
+smaller than B<RSA_size(rsa)>). B<padding> 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(rsa)). RSA_private_decrypt() returns the size of the
+recovered plaintext.
+
+On error, -1 is returned; the error codes can be
+obtained by ERR_get_error(3).
+
+=head1 CONFORMING TO
+
+SSL, PKCS #1 v2.0
+
+=head1 SEE ALSO
+
+err(3), rand(3), rsa(3), RSA_size(3)
+
+=head1 NOTES
+
+The RSA_PKCS1_RSAref(3) method supports only the RSA_PKCS1_PADDING mode.
+
+=head1 HISTORY
+
+The B<padding> 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/doc/crypto/RSA_set_method.pod b/doc/crypto/RSA_set_method.pod
new file mode 100644 (file)
index 0000000..8da805f
--- /dev/null
@@ -0,0 +1,153 @@
+=pod
+
+=head1 NAME
+
+RSA_set_default_method, RSA_get_default_method, RSA_set_method,
+RSA_get_method, RSA_PKCS1_SSLeay, RSA_PKCS1_RSAref,
+RSA_PKCS1_null_method, RSA_flags, RSA_new_method - Select RSA method
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ void RSA_set_default_method(RSA_METHOD *meth);
+
+ RSA_METHOD *RSA_get_default_method(void);
+
+ RSA_METHOD *RSA_set_method(RSA *rsa, RSA_METHOD *meth);
+
+ RSA_METHOD *RSA_get_method(RSA *rsa);
+
+ RSA_METHOD *RSA_PKCS1_SSLeay(void);
+
+ RSA_METHOD *RSA_PKCS1_RSAref(void);
+
+ RSA_METHOD *RSA_null_method(void);
+
+ int RSA_flags(RSA *rsa);
+
+ RSA *RSA_new_method(RSA_METHOD *method);
+
+=head1 DESCRIPTION
+
+An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA
+operations. By modifying the method, alternative implementations
+such as hardware accelerators may be used.
+
+Initially, the default is to use the OpenSSL internal implementation,
+unless OpenSSL was configured with the C<rsaref> or C<-DRSA_NULL>
+options. RSA_PKCS1_SSLeay() returns a pointer to that method.
+
+RSA_PKCS1_RSAref() returns a pointer to a method that uses the RSAref
+library. This is the default method in the C<rsaref> configuration;
+the function is not available in other configurations.
+RSA_null_method() returns a pointer to a method that does not support
+the RSA transformation. It is the default if OpenSSL is compiled with
+C<-DRSA_NULL>. These methods may be useful in the USA because of a
+patent on the RSA cryptosystem.
+
+RSA_set_default_method() makes B<meth> the default method for all B<RSA>
+structures created later.
+
+RSA_get_default_method() returns a pointer to the current default
+method.
+
+RSA_set_method() selects B<meth> for all operations using the key
+B<rsa>.
+
+RSA_get_method() returns a pointer to the method currently selected
+for B<rsa>.
+
+RSA_flags() returns the B<flags> that are set for B<rsa>'s current method.
+
+RSA_new_method() allocates and initializes an B<RSA> structure so that
+B<method> will be used for the RSA operations. If B<method> is B<NULL>,
+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 */
+       int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);
+
+     /* compute r = a ^ p mod m. May be NULL */
+       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_RSAref(), RSA_PKCS1_null_method(),
+RSA_get_default_method() and RSA_get_method() return pointers to the
+respective B<RSA_METHOD>s.
+
+RSA_set_default_method() returns no value.
+
+RSA_set_method() returns a pointer to the B<RSA_METHOD> previously
+associated with B<rsa>.
+
+RSA_new_method() returns B<NULL> and sets an error code that can be
+obtained by ERR_get_error(3) if the allocation fails. Otherwise it
+returns a pointer to the newly allocated structure.
+
+=head1 SEE ALSO
+
+rsa(3), RSA_new(3)
+
+=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.
+
+=cut
diff --git a/doc/crypto/RSA_sign.pod b/doc/crypto/RSA_sign.pod
new file mode 100644 (file)
index 0000000..81771ba
--- /dev/null
@@ -0,0 +1,63 @@
+=pod
+
+=head1 NAME
+
+RSA_sign, RSA_verify - RSA signatures
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ 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);
+
+=head1 DESCRIPTION
+
+RSA_sign() signs the message digest B<m> of size B<m_len> using the
+private key B<rsa> as specified in PKCS #1 v2.0. It stores the
+signature in B<sigret> and the signature size in B<siglen>. B<sigret>
+must point to B<RSA_size(rsa)> bytes of memory.
+
+B<type> denotes the message digest algorithm that was used to generate
+B<m>. It usually is one of B<NID_sha1>, B<NID_ripemd160> and
+B<NID_md5>; see L<objects> for details. If B<type> is B<NID_md5_sha1>,
+an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding
+and no algorithm identifier) is created.
+
+The random number generator must be seeded prior to calling RSA_sign().
+
+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
+
+RSA_sign() returns 1 on success, 0 otherwise.  RSA_verify() returns 1
+on successful verification, 0 otherwise.
+
+The error codes can be obtained by ERR_get_error(3).
+
+=head1 BUGS
+
+Certain signatures with an improper algorithm identifier are accepted
+for compatibility with SSLeay 0.4.5 :-)
+
+=head1 CONFORMING TO
+
+SSL, PKCS #1 v2.0
+
+=head1 SEE ALSO
+
+err(3), objects(3), rand(3), rsa(3), RSA_private_encrypt(3),
+RSA_public_decrypt(3)
+
+=head1 HISTORY
+
+RSA_sign() and RSA_verify() are available in all versions of SSLeay
+and OpenSSL.
+
+=cut
diff --git a/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod b/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod
new file mode 100644 (file)
index 0000000..e54660a
--- /dev/null
@@ -0,0 +1,57 @@
+=pod
+
+=head1 NAME
+
+RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING - RSA signatures
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ 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<m> of size
+B<m_len> using the private key B<rsa> represented in DER using PKCS #1
+padding. It stores the signature in B<sigret> and the signature size
+in B<siglen>. B<sigret> must point to B<RSA_size(rsa)> bytes of
+memory.
+
+B<dummy> is ignored.
+
+The random number generator must be seeded prior to calling RSA_sign_ASN1_OCTET_STRING().
+
+RSA_verify_ASN1_OCTET_STRING() verifies that the signature B<sigbuf>
+of size B<siglen> is the DER representation of a given octet string
+B<m> of size B<m_len>. B<dummy> is ignored. B<rsa> 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 ERR_get_error(3).
+
+=head1 BUGS
+
+These functions serve no recognizable purpose.
+
+=head1 SEE ALSO
+
+err(3), objects(3), rand(3), rsa(3), RSA_sign(3), RSA_verify(3)
+
+=head1 HISTORY
+
+RSA_sign_ASN1_OCTET_STRING() and RSA_verify_ASN1_OCTET_STRING() were
+added in SSLeay 0.8.
+
+=cut
diff --git a/doc/crypto/RSA_size.pod b/doc/crypto/RSA_size.pod
new file mode 100644 (file)
index 0000000..9af1c40
--- /dev/null
@@ -0,0 +1,33 @@
+=pod
+
+=head1 NAME
+
+RSA_size - Get RSA modulus size
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ int RSA_size(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.
+
+B<rsa->n> must not be B<NULL>.
+
+=head1 RETURN VALUE
+
+The size in bytes.
+
+=head1 SEE ALSO
+
+rsa(3)
+
+=head1 HISTORY
+
+RSA_size() is available in all versions of SSLeay and OpenSSL.
+
+=cut
diff --git a/doc/crypto/crypto.pod b/doc/crypto/crypto.pod
new file mode 100644 (file)
index 0000000..101058f
--- /dev/null
@@ -0,0 +1,62 @@
+=pod
+
+=head1 NAME
+
+crypto - OpenSSL cryptographic library
+
+=head1 SYNOPSIS
+
+=head1 DESCRIPTION
+
+The OpenSSL B<crypto> library implements a wide range of cryptographic
+algorithms used in various Internet standards. The services provided
+by this library are used by the OpenSSL implementations of SSL, TLS
+and S/MIME, and they have also been used to implement SSH, OpenPGP, and
+other cryptographic standards.
+
+=head1 OVERVIEW
+
+B<libcrypto> consists of a number of sub-libraries that implement the
+individual algorithms.
+
+The functionality includes symmetric encryption, public key
+cryptography and key agreement, certificate handling, cryptographic
+hash functions and a cryptographic pseudo-random number generator.
+
+=over 4
+
+=item SYMMETRIC CIPHERS
+
+blowfish(3), cast(3), des(3), idea(3), rc2(3), rc4(3), rc5(3)
+
+=item PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT
+
+dsa(3), dh(3), rsa(3)
+
+=item CERTIFICATES
+
+x509(3), x509v3(3)
+
+=item AUTHENTICATION CODES, HASH FUNCTIONS
+
+hmac(3), md2(3), md5(3), mdc2(3), ripemd(3), sha(3)
+
+=item AUXILIARY FUNCTIONS
+
+err(3), rand(3)
+
+=item INPUT/OUTPUT, DATA ENCODING
+
+asn1(3), bio(3), evp(3), pem(3), pkcs7(3), pkcs12(3)
+
+=item INTERNAL FUNCTIONS
+
+bn(3), buffer(3), lhash(3), objects(3), stack(3), threads(3), txt_db(3)
+
+=back
+
+=head1 SEE ALSO
+
+openssl(1), ssl(3)
+
+=cut
diff --git a/doc/crypto/d2i_RSAPublicKey.pod b/doc/crypto/d2i_RSAPublicKey.pod
new file mode 100644 (file)
index 0000000..776ade1
--- /dev/null
@@ -0,0 +1,39 @@
+=pod
+
+=head1 NAME
+
+d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey, i2d_Netscape_RSA, d2i_Netscape_RSA - ...
+
+=head1 SYNOPSIS
+
+#include <openssl/rsa.h>
+
+ RSA * d2i_RSAPublicKey(RSA **a, unsigned char **pp, long length);
+
+ int i2d_RSAPublicKey(RSA *a, unsigned char **pp);
+
+ RSA * d2i_RSAPrivateKey(RSA **a, 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, unsigned char **pp, long length, int (*cb)());
+
+=head1 DESCRIPTION
+
+...
+
+=head1 RETURN VALUES
+
+...
+
+=head1 SEE ALSO
+
+...
+
+=head1 HISTORY
+
+...
+
+=cut
diff --git a/doc/crypto/rsa.pod b/doc/crypto/rsa.pod
new file mode 100644 (file)
index 0000000..fafe337
--- /dev/null
@@ -0,0 +1,152 @@
+=pod
+
+=head1 NAME
+
+rsa - RSA public key cryptosystem
+
+=head1 SYNOPSIS
+
+ #include <openssl/rsa.h>
+
+ 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_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(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(RSA_METHOD *meth);
+
+ RSA_METHOD *RSA_get_default_method(void);
+
+ RSA_METHOD *RSA_set_method(RSA *rsa, RSA_METHOD *meth);
+
+ RSA_METHOD *RSA_get_method(RSA *rsa);
+
+ RSA_METHOD *RSA_PKCS1_SSLeay(void);
+
+ RSA_METHOD *RSA_PKCS1_RSAref(void);
+
+ RSA_METHOD *RSA_null_method(void);
+
+ int RSA_flags(RSA *rsa);
+
+ RSA *RSA_new_method(RSA_METHOD *method);
+
+ 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_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_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);
+
+ 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
+
+These functions implement RSA public key encryption and signatures
+as defined in PKCS #1 v2.0 [RFC 2437].
+
+The B<RSA> 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<NULL>.
+
+B<dmp1>, B<dmq1> and B<iqmp> may be B<NULL> in private keys, but the
+RSA operations are much faster when these values are available.
+
+=head1 PATENTS
+
+RSA is covered by a US patent which expires in September 2000.
+
+=head1 SEE ALSO
+
+rsa(1), bn(3), dsa(3), dh(3), rand(3), RSA_new(3),
+RSA_public_encrypt(3), RSA_sign(3), RSA_size(3), RSA_generate_key(3),
+RSA_check_key(3), RSA_blinding_on(3), RSA_set_method(3), RSA_print(3),
+RSA_get_ex_new_index(3), RSA_private_encrypt(3),
+RSA_sign_ASN_OCTET_STRING(3), RSA_padding_add_PKCS1_type_1(3)
+
+=cut