From f75416634e50d0e872512d4248c52af59ba54ba3 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sun, 25 Dec 2016 18:39:35 +0000 Subject: 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. --- src/lib/libcrypto/man/d2i_ECPKParameters.3 | 70 +++++++++++++++++++++++++----- 1 file changed, 59 insertions(+), 11 deletions(-) (limited to 'src/lib') 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 . +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016 Ingo Schwarze +.\" +.\" 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 . .\" 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 -- cgit v1.2.3-55-g6feb