From 57e1f989d9fcf62c64f0a5143c2213a4c5d321a2 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Mon, 26 Dec 2016 16:36:34 +0000 Subject: Basic cleanup: Simplify one-line description. List each function with the correct header file. Use the same parameter names as in ASN1_item_d2i(3). Point to ASN1_item_d2i(3) for details. Sort the text. Add some useful cross references. --- src/lib/libcrypto/man/d2i_RSAPublicKey.3 | 182 +++++++++++++++++-------------- 1 file changed, 102 insertions(+), 80 deletions(-) (limited to 'src/lib') diff --git a/src/lib/libcrypto/man/d2i_RSAPublicKey.3 b/src/lib/libcrypto/man/d2i_RSAPublicKey.3 index 22d904157f..7a65bed7a4 100644 --- a/src/lib/libcrypto/man/d2i_RSAPublicKey.3 +++ b/src/lib/libcrypto/man/d2i_RSAPublicKey.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: d2i_RSAPublicKey.3,v 1.6 2016/12/25 22:15:10 schwarze Exp $ +.\" $OpenBSD: d2i_RSAPublicKey.3,v 1.7 2016/12/26 16:36:34 schwarze Exp $ .\" OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400 .\" .\" This file was written by Ulf Moeller and @@ -50,93 +50,97 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 25 2016 $ +.Dd $Mdocdate: December 26 2016 $ .Dt D2I_RSAPUBLICKEY 3 .Os .Sh NAME .Nm d2i_RSAPublicKey , .Nm i2d_RSAPublicKey , +.Nm d2i_RSAPrivateKey , +.Nm i2d_RSAPrivateKey , +.Nm d2i_Netscape_RSA , +.Nm i2d_Netscape_RSA , .Nm d2i_RSA_PUBKEY , .Nm i2d_RSA_PUBKEY , .Nm d2i_RSA_PUBKEY_bio , .Nm d2i_RSA_PUBKEY_fp , .Nm i2d_RSA_PUBKEY_bio , -.Nm i2d_RSA_PUBKEY_fp , -.Nm d2i_RSAPrivateKey , -.Nm i2d_RSAPrivateKey , -.Nm i2d_Netscape_RSA , -.Nm d2i_Netscape_RSA -.Nd RSA public and private key encoding functions +.Nm i2d_RSA_PUBKEY_fp +.Nd decode and encode RSA keys .Sh SYNOPSIS .In openssl/rsa.h -.In openssl/x509.h .Ft RSA * .Fo d2i_RSAPublicKey -.Fa "RSA **a" -.Fa "const unsigned char **pp" +.Fa "RSA **val_out" +.Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_RSAPublicKey -.Fa "RSA *a" -.Fa "unsigned char **pp" +.Fa "RSA *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft RSA * +.Fo d2i_RSAPrivateKey +.Fa "RSA **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_RSAPrivateKey +.Fa "RSA *val_in" +.Fa "unsigned char **der_out" +.Fc +.Ft RSA * +.Fo d2i_Netscape_RSA +.Fa "RSA **val_out" +.Fa "const unsigned char **der_in" +.Fa "long length" +.Fa "int (*cb)()" +.Fc +.Ft int +.Fo i2d_Netscape_RSA +.Fa "RSA *val_in" +.Fa "unsigned char **der_out" +.Fa "int (*cb)()" .Fc +.In openssl/x509.h .Ft RSA * .Fo d2i_RSA_PUBKEY -.Fa "RSA **a" -.Fa "const unsigned char **pp" +.Fa "RSA **val_out" +.Fa "const unsigned char **der_in" .Fa "long length" .Fc .Ft int .Fo i2d_RSA_PUBKEY -.Fa "RSA *a" -.Fa "unsigned char **pp" +.Fa "RSA *val_in" +.Fa "unsigned char **der_out" .Fc .Ft RSA * .Fo d2i_RSA_PUBKEY_bio -.Fa "BIO *bp" -.Fa "RSA **a" +.Fa "BIO *in_bio" +.Fa "RSA **val_out" .Fc .Ft RSA * .Fo d2i_RSA_PUBKEY_fp -.Fa "FILE *fp" -.Fa "RSA **a" +.Fa "FILE *in_fp" +.Fa "RSA **val_out" .Fc .Ft int .Fo i2d_RSA_PUBKEY_bio -.Fa "BIO *bp" -.Fa "RSA *a" +.Fa "BIO *out_bio" +.Fa "RSA *val_in" .Fc .Ft int .Fo i2d_RSA_PUBKEY_fp -.Fa "FILE *fp" -.Fa "RSA *a" -.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)()" +.Fa "FILE *out_fp" +.Fa "RSA *val_in" .Fc .Sh DESCRIPTION +These functions decode and encode RSA private and public keys. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp .Fn d2i_RSAPublicKey and .Fn i2d_RSAPublicKey @@ -144,55 +148,73 @@ decode and encode a PKCS#1 .Vt RSAPublicKey structure. .Pp +.Fn d2i_RSAPrivateKey +and +.Fn i2d_RSAPrivateKey +decode and encode a PKCS#1 +.Vt RSAPrivateKey +structure. +The +.Vt RSA +structure passed to the private key encoding functions should have +all the PKCS#1 private key components present. +The data encoded by the private key functions is unencrypted and +therefore offers no private key security. +.Pp +.Fn d2i_Netscape_RSA +and +.Fn i2d_Netscape_RSA +decode and encode an RSA private key in NET format. +These functions are present to provide compatibility with +certain very old software. +The NET format has some severe security weaknesses and should be +avoided if possible. +.Pp .Fn d2i_RSA_PUBKEY and .Fn i2d_RSA_PUBKEY decode and encode an RSA public key using an ASN.1 .Vt SubjectPublicKeyInfo -(certificate public key) structure. -.Pp +structure. .Fn d2i_RSA_PUBKEY_bio , .Fn d2i_RSA_PUBKEY_fp , .Fn i2d_RSA_PUBKEY_bio , and .Fn i2d_RSA_PUBKEY_fp -are similar to -.Fn d2i_RSA_PUBKEY -and -.Fn i2d_RSA_PUBKEY -except that they decode or encode using a +are similar except that they decode or encode using a .Vt BIO or .Vt FILE pointer. -.Pp +.Sh RETURN VALUES +.Fn d2i_RSAPublicKey , .Fn d2i_RSAPrivateKey , -.Fn i2d_RSAPrivateKey -decode and encode a PKCS#1 -.Vt 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 +.Fn d2i_RSA_PUBKEY , +.Fn d2i_RSA_PUBKEY_bio , and -.Xr i2d_X509 3 . -.Pp -The +.Fn d2i_RSA_PUBKEY_fp +return a valid .Vt RSA -structure passed to the private key encoding functions should have all -the PKCS#1 private key components present. +object or +.Dv NULL +if an error occurs. .Pp -The data encoded by the private key functions is unencrypted and -therefore offers no private key security. +.Fn i2d_RSAPublicKey , +.Fn i2d_RSAPrivateKey , +.Fn i2d_Netscape_RSA , +and +.Fn i2d_RSA_PUBKEY +return the number of bytes successfully encoded or a negative value +if an error occurs. .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. +.Fn i2d_RSA_PUBKEY_bio +and +.Fn i2d_RSA_PUBKEY_fp +return 1 for success or 0 if an error occurs. .Sh SEE ALSO -.Xr d2i_X509 3 , -.Xr RSA_new 3 +.Xr ASN1_item_d2i 3 , +.Xr EVP_PKEY_set1_RSA 3 , +.Xr PEM_write_RSAPrivateKey 3 , +.Xr RSA_new 3 , +.Xr X509_PUBKEY_new 3 -- cgit v1.2.3-55-g6feb