convert RSA manuals from pod to mdoc

1 files changed, 238 insertions, 0 deletions

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.