From 2186cd8ef1c4db86109af7a38182c2bd9ddbbb32 Mon Sep 17 00:00:00 2001 From: Ulf Möller Date: Tue, 11 Jan 2000 22:35:21 +0000 Subject: Document the RSA library. --- doc/crypto/RSA_blinding_on.pod | 43 ++++++++ doc/crypto/RSA_check_key.pod | 39 +++++++ doc/crypto/RSA_generate_key.pod | 68 +++++++++++++ doc/crypto/RSA_get_ex_new_index.pod | 34 +++++++ doc/crypto/RSA_new.pod | 38 +++++++ doc/crypto/RSA_padding_add_PKCS1_type_1.pod | 120 ++++++++++++++++++++++ doc/crypto/RSA_print.pod | 31 ++++++ doc/crypto/RSA_private_encrypt.pod | 72 +++++++++++++ doc/crypto/RSA_public_encrypt.pod | 86 ++++++++++++++++ doc/crypto/RSA_set_method.pod | 153 ++++++++++++++++++++++++++++ doc/crypto/RSA_sign.pod | 63 ++++++++++++ doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod | 57 +++++++++++ doc/crypto/RSA_size.pod | 33 ++++++ doc/crypto/crypto.pod | 62 +++++++++++ doc/crypto/d2i_RSAPublicKey.pod | 39 +++++++ doc/crypto/rsa.pod | 152 +++++++++++++++++++++++++++ 16 files changed, 1090 insertions(+) create mode 100644 doc/crypto/RSA_blinding_on.pod create mode 100644 doc/crypto/RSA_check_key.pod create mode 100644 doc/crypto/RSA_generate_key.pod create mode 100644 doc/crypto/RSA_get_ex_new_index.pod create mode 100644 doc/crypto/RSA_new.pod create mode 100644 doc/crypto/RSA_padding_add_PKCS1_type_1.pod create mode 100644 doc/crypto/RSA_print.pod create mode 100644 doc/crypto/RSA_private_encrypt.pod create mode 100644 doc/crypto/RSA_public_encrypt.pod create mode 100644 doc/crypto/RSA_set_method.pod create mode 100644 doc/crypto/RSA_sign.pod create mode 100644 doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod create mode 100644 doc/crypto/RSA_size.pod create mode 100644 doc/crypto/crypto.pod create mode 100644 doc/crypto/d2i_RSAPublicKey.pod create mode 100644 doc/crypto/rsa.pod (limited to 'doc/crypto') diff --git a/doc/crypto/RSA_blinding_on.pod b/doc/crypto/RSA_blinding_on.pod new file mode 100644 index 0000000000..41707df360 --- /dev/null +++ b/doc/crypto/RSA_blinding_on.pod @@ -0,0 +1,43 @@ +=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 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 and generates a +random blinding factor. B is B or a pre-allocated and +initialized B. 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 index 0000000000..c1b9507e87 --- /dev/null +++ b/doc/crypto/RSA_check_key.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +RSA_check_key - Validate 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. + +In the case of private keys, it also checks that B, +and that B, B and B are set correctly or are B. + +The key's public components may not be B. + +=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 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 index 0000000000..cdf527069a --- /dev/null +++ b/doc/crypto/RSA_generate_key.pod @@ -0,0 +1,68 @@ +=pod + +=head1 NAME + +RSA_generate_key - Generate RSA key pair + +=head1 SYNOPSIS + + #include + + 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 structure. The pseudo-random number generator must +be seeded prior to calling RSA_generate_key(). + +The modulus size will be B bits, 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 or 65535. + +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: + +=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. + +=head1 RETURN VALUES + +If key generation fails, RSA_generate_key() returns B; the +error codes can be obtained by ERR_get_error(3). + +=head1 BUGS + +B 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 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 index 0000000000..2afcc20401 --- /dev/null +++ b/doc/crypto/RSA_get_ex_new_index.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - ... + +=head1 SYNOPSIS + + #include + + 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 index 0000000000..a5df37777f --- /dev/null +++ b/doc/crypto/RSA_new.pod @@ -0,0 +1,38 @@ +=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. + +RSA_free() frees the B 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 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 index 0000000000..564ac02091 --- /dev/null +++ b/doc/crypto/RSA_padding_add_PKCS1_type_1.pod @@ -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 + + 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 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 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 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 +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 +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 index 0000000000..2361daa10e --- /dev/null +++ b/doc/crypto/RSA_print.pod @@ -0,0 +1,31 @@ +=pod + +=head1 NAME + +RSA_print, RSA_print_fp - Print RSA key + +=head1 SYNOPSIS + + #include + + 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 index 0000000000..59ab49d41f --- /dev/null +++ b/doc/crypto/RSA_private_encrypt.pod @@ -0,0 +1,72 @@ +=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, RSA_sign(3) and RSA_verify(3) 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 + +The random number generator must be seeded prior to calling +RSA_private_encrypt(). + +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 ERR_get_error(3). + +=head1 SEE ALSO + +err(3), rand(3), rsa(3), RSA_sign(3), RSA_verify(3) + +=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/doc/crypto/RSA_public_encrypt.pod b/doc/crypto/RSA_public_encrypt.pod new file mode 100644 index 0000000000..a7b51e99cd --- /dev/null +++ b/doc/crypto/RSA_public_encrypt.pod @@ -0,0 +1,86 @@ +=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 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(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 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 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(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 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 index 0000000000..8da805ff07 --- /dev/null +++ b/doc/crypto/RSA_set_method.pod @@ -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 + + 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 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 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 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 the default method for all B +structures created later. + +RSA_get_default_method() returns a pointer to the current default +method. + +RSA_set_method() selects B for all operations using the key +B. + +RSA_get_method() returns a pointer to the method currently selected +for B. + +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 */ + 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 Bs. + +RSA_set_default_method() returns no value. + +RSA_set_method() returns a pointer to the B previously +associated with B. + +RSA_new_method() returns B 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 index 0000000000..81771ba574 --- /dev/null +++ b/doc/crypto/RSA_sign.pod @@ -0,0 +1,63 @@ +=pod + +=head1 NAME + +RSA_sign, RSA_verify - RSA signatures + +=head1 SYNOPSIS + + #include + + 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 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 B bytes of memory. + +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. + +The random number generator must be seeded prior to calling RSA_sign(). + +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 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 index 0000000000..e54660aa23 --- /dev/null +++ b/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod @@ -0,0 +1,57 @@ +=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. + +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 +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 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 index 0000000000..9af1c40f1a --- /dev/null +++ b/doc/crypto/RSA_size.pod @@ -0,0 +1,33 @@ +=pod + +=head1 NAME + +RSA_size - Get RSA modulus size + +=head1 SYNOPSIS + + #include + + 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. + +Bn> must not be B. + +=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 index 0000000000..101058f55b --- /dev/null +++ b/doc/crypto/crypto.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +crypto - OpenSSL cryptographic library + +=head1 SYNOPSIS + +=head1 DESCRIPTION + +The OpenSSL B 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 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 index 0000000000..776ade1527 --- /dev/null +++ b/doc/crypto/d2i_RSAPublicKey.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey, i2d_Netscape_RSA, d2i_Netscape_RSA - ... + +=head1 SYNOPSIS + +#include + + 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 index 0000000000..fafe337a4b --- /dev/null +++ b/doc/crypto/rsa.pod @@ -0,0 +1,152 @@ +=pod + +=head1 NAME + +rsa - RSA public key cryptosystem + +=head1 SYNOPSIS + + #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_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 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 and B may be B 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 -- cgit v1.2.3