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/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 +++++++++++++++ 16 files changed, 1919 insertions(+), 16 deletions(-) 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/libcrypto/man') 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