Correct the DESCRIPTION of ECParameters_dup(3).

Clarify requirements for o2i_ECPublicKey(3).
Add STANDARDS references for d2i_ECPrivateKey(3) and d2i_EC_PUBKEY(3).
Trim some excessive cross references that are only tangentially
related and add some more relevant ones instead.

1 files changed, 59 insertions, 11 deletions

diff --git a/src/lib/libcrypto/man/d2i_ECPKParameters.3 b/src/lib/libcrypto/man/d2i_ECPKParameters.3
index 3ad7c16cab..51080d6918 100644
--- a/src/lib/libcrypto/man/d2i_ECPKParameters.3
+++ b/src/lib/libcrypto/man/d2i_ECPKParameters.3
@@ -1,7 +1,24 @@
-.\"     $OpenBSD: d2i_ECPKParameters.3,v 1.8 2016/12/25 17:05:59 schwarze Exp $
+.\"     $OpenBSD: d2i_ECPKParameters.3,v 1.9 2016/12/25 18:39:35 schwarze Exp $
 .\"     OpenSSL 05ea606a May 20 20:52:46 2016 -0400
 .\"
-.\" This file was written by Matt Caswell <matt@openssl.org>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" The original file was written by Matt Caswell <matt@openssl.org>.
 .\" Copyright (c) 2013, 2015 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -263,17 +280,28 @@ for input instead of
 .Fa val_in .
 .Pp
 .Fn ECParameters_dup
-copies
+allocates and initializes an empty
+.Vt EC_KEY
+object and copies the EC parameters from
 .Fa val_in
-by calling
+to it by calling
 .Fn i2d_ECParameters
 and
 .Fn d2i_ECParameters .
+If a private or public key or any flags are present in
+.Fa val_in ,
+they are not copied.
 .Pp
 .Fn d2i_ECPrivateKey
 and
 .Fn i2d_ECPrivateKey
-decode and encode an EC private key.
+decode and encode an EC private key using an ASN.1
+.Vt ECPrivateKey
+structure defined in RFC 5915 section 3 and used for the privateKey
+field of the ASN.1
+.Vt PrivateKeyInfo
+structure defined in RFC 5208 section 5, see
+.Xr PKCS8_PRIV_KEY_INFO_new 3 .
 .Fn d2i_ECPrivateKey_bio ,
 .Fn i2d_ECPrivateKey_bio ,
 .Fn d2i_ECPrivateKey_fp ,
@@ -289,8 +317,16 @@ pointer.
 and
 .Fn i2o_ECPublicKey
 decode and encode an EC public key.
+In contrast to
+.Xr ASN1_item_d2i 3 ,
 .Fn o2i_ECPublicKey
-can store a key into an existing object.
+requires
+.Fa val_out ,
+.Pf * Fa val_out ,
+and
+.Po Pf * Fa val_out Pc Ns -> Ns Fa group
+to be
+.Pf non- Dv NULL .
 .Pp
 .Fn ECPKParameters_print
 and
@@ -318,7 +354,10 @@ or
 .Fn d2i_EC_PUBKEY
 and
 .Fn i2d_EC_PUBKEY
-decode and encode an EC public key.
+decode and encode an EC public key using an ASN.1
+.Vt SubjectPublicKeyInfo
+structure defined in RFC 5280 section 4.1 and documented in
+.Xr X509_PUBKEY_new 3 .
 .Fn d2i_EC_PUBKEY_bio ,
 .Fn i2d_EC_PUBKEY_bio ,
 .Fn d2i_EC_PUBKEY_fp ,
@@ -379,10 +418,19 @@ and
 return 1 for success or 0 if an error occurs.
 .Sh SEE ALSO
 .Xr ASN1_item_d2i 3 ,
-.Xr EC_GFp_simple_method 3 ,
 .Xr EC_GROUP_copy 3 ,
 .Xr EC_GROUP_new 3 ,
 .Xr EC_KEY_new 3 ,
-.Xr EC_POINT_add 3 ,
-.Xr EC_POINT_new 3 ,
-.Xr ECDSA_SIG_new 3
+.Xr EVP_PKEY_set1_EC_KEY 3 ,
+.Xr PEM_write_ECPrivateKey 3 ,
+.Xr PKCS8_PRIV_KEY_INFO_new 3 ,
+.Xr X509_PUBKEY_new 3
+.Sh STANDARDS
+RFC 5915: Elliptic Curve Private Key Structure
+.Pp
+RFC 5208: Public-Key Cryptography Standards (PKCS) #8:
+Private-Key Information Syntax Specification
+.Pp
+RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
+Certificate Revocation List (CRL) Profile,
+section 4.1: Basic Certificate Fields