Chiebot-Mirror
/
boringssl
8
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Deduplicate d2i and i2d documentation.

Browse Source 
There are a lot of d2i and i2d functions, and there will be even more
once asn1.h and x509.h are properly documented. We currently replicate
the text in each, but as a result a miss a few points:

- The i2d outp != NULL, *outp == NULL case isn't documented at all.

- We should call out what to do with *inp after d2i.

- Unlike our rewritten functions, object reuse is still quite rampant
  with the asn1.h functions. I hope we can get rid of that but, until we
  can, it would be nice to describe it in one place.

While I'm here, update a few references to the latest PKCS#1 RFC, and
try to align how we reference ASN.1 structures a bit. The d2i/i2d
functions say "ASN.1, DER-encoded RSA private key" while the CBS/CBB
functions say "DER-encoded RSAPrivateKey structure".

Bug: 426
Change-Id: I8d9a7b0aef3d6d9c8240136053c3b1704b09fd41
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/49906
Reviewed-by: Adam Langley <agl@google.com>
grpc-202302
David Benjamin 3 years ago committed by Adam Langley
parent f6ef1c560a
commit cfafcd454f
11 changed files with 188 additions and 232 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 4
      crypto/evp/evp_asn1.c
  2. 78
      include/openssl/bytestring.h
  3. 16
      include/openssl/dh.h
  4. 58
      include/openssl/dsa.h
  5. 39
      include/openssl/ec_key.h
  6. 18
      include/openssl/ecdsa.h
  7. 84
      include/openssl/evp.h
  8. 12
      include/openssl/pkcs7.h
  9. 52
      include/openssl/rsa.h
  10. 11
      include/openssl/ssl.h
  11. 48
      include/openssl/x509.h

4
crypto/evp/evp_asn1.c
Unescape View File

@ -369,8 +369,8 @@ EVP_PKEY *d2i_PublicKey(int type, EVP_PKEY **out, const uint8_t **inp,
// Unlike OpenSSL, we do not support EC keys with this API. The raw EC
// public key serialization requires knowing the group. In OpenSSL, calling
// this function with |EVP_PKEY_EC| and setting |out| to NULL does not work.
// It requires |*out| to include a partially-initiazed |EVP_PKEY| to extract
// the group.
// It requires |*out| to include a partially-initialized |EVP_PKEY| to
// extract the group.
default:
OPENSSL_PUT_ERROR(EVP, EVP_R_UNSUPPORTED_PUBLIC_KEY_TYPE);
goto err;

78
include/openssl/bytestring.h
Unescape View File

@ -565,6 +565,84 @@ OPENSSL_EXPORT int CBB_add_asn1_oid_from_text(CBB *cbb, const char *text,
OPENSSL_EXPORT int CBB_flush_asn1_set_of(CBB *cbb);
// Legacy ASN.1 API conventions.
//
// The following sample functions document the calling conventions used by
// legacy ASN.1 APIs.
//
// TODO(https://crbug.com/boringssl/426): When asn1.h is fully documented and
// added to doc.go, move this section to asn1.h.
#if 0 // Sample functions
// d2i_SAMPLE parses a structure from up to |len| bytes at |*inp|. On success,
// it advances |*inp| by the number of bytes read and returns a newly-allocated
// |SAMPLE| object containing the parsed structure. If |out| is non-NULL, it
// additionally frees the previous value at |*out| and updates |*out| to the
// result. If parsing or allocating the result fails, it returns NULL.
//
// This function does not reject trailing data in the input. This allows the
// caller to parse a sequence of concatenated structures. Callers parsing only
// one structure should check for trailing data by comparing the updated |*inp|
// with the end of the input.
//
// Note: If |out| and |*out| are both non-NULL, the object at |*out| is not
// updated in-place. Instead, it is freed, and the pointer is updated to the
// new object. This differs from OpenSSL, which behaves more like
// |d2i_SAMPLE_with_reuse|. Callers are recommended to set |out| to NULL and
// instead use the return value.
SAMPLE *d2i_SAMPLE(SAMPLE **out, const uint8_t **inp, long len);
// d2i_SAMPLE_with_reuse parses a structure from up to |len| bytes at |*inp|. On
// success, it advances |*inp| by the number of bytes read and returns a
// non-NULL pointer to an object containing the parsed structure. The object is
// determined from |out| as follows:
//
// If |out| is NULL, the function places the result in a newly-allocated
// |SAMPLE| object and returns it. This mode is recommended.
//
// If |out| is non-NULL, but |*out| is NULL, the function also places the result
// in a newly-allocated |SAMPLE| object. It sets |*out| to this object and also
// returns it.
//
// If |out| and |*out| are both non-NULL, the function updates the object at
// |*out| in-place with the result and returns |*out|.
//
// If any of the above fail, the function returns NULL.
//
// This function does not reject trailing data in the input. This allows the
// caller to parse a sequence of concatenated structures. Callers parsing only
// one structure should check for trailing data by comparing the updated |*inp|
// with the end of the input.
//
// WARNING: Callers should not rely on the in-place update mode. It often
// produces the wrong result or breaks the type's internal invariants. Future
// revisions of BoringSSL may standardize on the |d2i_SAMPLE| behavior.
SAMPLE *d2i_SAMPLE_with_reuse(SAMPLE **out, const uint8_t **inp, long len);
// i2d_SAMPLE marshals |in|. On error, it returns a negative value. On success,
// it returns the length of the result and outputs it via |outp| as follows:
//
// If |outp| is NULL, the function writes nothing. This mode can be used to size
// buffers.
//
// If |outp| is non-NULL but |*outp| is NULL, the function sets |*outp| to a
// newly-allocated buffer containing the result. The caller is responsible for
// releasing |*outp| with |OPENSSL_free|. This mode is recommended for most
// callers.
//
// If |outp| and |*outp| are non-NULL, the function writes the result to
// |*outp|, which must have enough space available, and advances |*outp| just
// past the output.
//
// WARNING: In the third mode, the function does not internally check output
// bounds. Failing to correctly size the buffer will result in a potentially
// exploitable memory error.
int i2d_SAMPLE(const SAMPLE *in, uint8_t **outp);
#endif // Sample functions
#if defined(__cplusplus)
} // extern C

16
include/openssl/dh.h
Unescape View File

@ -267,22 +267,14 @@ OPENSSL_EXPORT DH *DH_generate_parameters(int prime_len, int generator,
void (*callback)(int, int, void *),
void *cb_arg);
// d2i_DHparams parses an ASN.1, DER encoded Diffie-Hellman parameters structure
// from |len| bytes at |*inp|. If |ret| is not NULL then, on exit, a pointer to
// the result is in |*ret|. Note that, even if |*ret| is already non-NULL on
// entry, it will not be written to. Rather, a fresh |DH| is allocated and the
// previous one is freed.
//
// On successful exit, |*inp| is advanced past the DER structure. It
// returns the result or NULL on error.
// d2i_DHparams parses a DER-encoded DHParameter structure (PKCS #3) from |len|
// bytes at |*inp|, as in |d2i_SAMPLE|.
//
// Use |DH_parse_parameters| instead.
OPENSSL_EXPORT DH *d2i_DHparams(DH **ret, const unsigned char **inp, long len);
// i2d_DHparams marshals |in| to an ASN.1, DER structure. If |outp| is not NULL
// then the result is written to |*outp| and |*outp| is advanced just past the
// output. It returns the number of bytes in the result, whether written or
// not, or a negative value on error.
// i2d_DHparams marshals |in| to a DER-encoded DHParameter structure (PKCS #3),
// as described in |i2d_SAMPLE|.
//
// Use |DH_marshal_parameters| instead.
OPENSSL_EXPORT int i2d_DHparams(const DH *in, unsigned char **outp);

58
include/openssl/dsa.h
Unescape View File

@ -299,7 +299,7 @@ OPENSSL_EXPORT int DSA_marshal_private_key(CBB *cbb, const DSA *dsa);
OPENSSL_EXPORT DSA *DSA_parse_parameters(CBS *cbs);
// DSA_marshal_parameters marshals |dsa| as a DER-encoded Dss-Parms structure
// (RFC 3447) and appends the result to |cbb|. It returns one on success and
// (RFC 3279) and appends the result to |cbb|. It returns one on success and
// zero on failure.
OPENSSL_EXPORT int DSA_marshal_parameters(CBB *cbb, const DSA *dsa);
@ -326,75 +326,51 @@ OPENSSL_EXPORT void *DSA_get_ex_data(const DSA *dsa, int idx);
// Deprecated functions.
// d2i_DSA_SIG parses an ASN.1, DER-encoded, DSA signature from |len| bytes at
// |*inp|. If |out_sig| is not NULL then, on exit, a pointer to the result is
// in |*out_sig|. Note that, even if |*out_sig| is already non-NULL on entry, it
// will not be written to. Rather, a fresh |DSA_SIG| is allocated and the
// previous one is freed. On successful exit, |*inp| is advanced past the DER
// structure. It returns the result or NULL on error.
// d2i_DSA_SIG parses a DER-encoded DSA-Sig-Value structure from |len| bytes at
// |*inp|, as described in |d2i_SAMPLE|.
//
// Use |DSA_SIG_parse| instead.
OPENSSL_EXPORT DSA_SIG *d2i_DSA_SIG(DSA_SIG **out_sig, const uint8_t **inp,
long len);
// i2d_DSA_SIG marshals |in| to an ASN.1, DER structure. If |outp| is not NULL
// then the result is written to |*outp| and |*outp| is advanced just past the
// output. It returns the number of bytes in the result, whether written or not,
// or a negative value on error.
// i2d_DSA_SIG marshals |in| to a DER-encoded DSA-Sig-Value structure, as
// described in |i2d_SAMPLE|.
//
// Use |DSA_SIG_marshal| instead.
OPENSSL_EXPORT int i2d_DSA_SIG(const DSA_SIG *in, uint8_t **outp);
// d2i_DSAPublicKey parses an ASN.1, DER-encoded, DSA public key from |len|
// bytes at |*inp|. If |out| is not NULL then, on exit, a pointer to the result
// is in |*out|. Note that, even if |*ou| is already non-NULL on entry, it will
// not be written to. Rather, a fresh |DSA| is allocated and the previous one is
// freed. On successful exit, |*inp| is advanced past the DER structure. It
// returns the result or NULL on error.
// d2i_DSAPublicKey parses a DER-encoded DSA public key from |len| bytes at
// |*inp|, as described in |d2i_SAMPLE|.
//
// Use |DSA_parse_public_key| instead.
OPENSSL_EXPORT DSA *d2i_DSAPublicKey(DSA **out, const uint8_t **inp, long len);
// i2d_DSAPublicKey marshals a public key from |in| to an ASN.1, DER structure.
// If |outp| is not NULL then the result is written to |*outp| and |*outp| is
// advanced just past the output. It returns the number of bytes in the result,
// whether written or not, or a negative value on error.
// i2d_DSAPublicKey marshals |in| as a DER-encoded DSA public key, as described
// in |i2d_SAMPLE|.
//
// Use |DSA_marshal_public_key| instead.
OPENSSL_EXPORT int i2d_DSAPublicKey(const DSA *in, uint8_t **outp);
// d2i_DSAPrivateKey parses an ASN.1, DER-encoded, DSA private key from |len|
// bytes at |*inp|. If |out| is not NULL then, on exit, a pointer to the result
// is in |*out|. Note that, even if |*out| is already non-NULL on entry, it will
// not be written to. Rather, a fresh |DSA| is allocated and the previous one is
// freed. On successful exit, |*inp| is advanced past the DER structure. It
// returns the result or NULL on error.
// d2i_DSAPrivateKey parses a DER-encoded DSA private key from |len| bytes at
// |*inp|, as described in |d2i_SAMPLE|.
//
// Use |DSA_parse_private_key| instead.
OPENSSL_EXPORT DSA *d2i_DSAPrivateKey(DSA **out, const uint8_t **inp, long len);
// i2d_DSAPrivateKey marshals a private key from |in| to an ASN.1, DER
// structure. If |outp| is not NULL then the result is written to |*outp| and
// |*outp| is advanced just past the output. It returns the number of bytes in
// the result, whether written or not, or a negative value on error.
// i2d_DSAPrivateKey marshals |in| as a DER-encoded DSA private key, as
// described in |i2d_SAMPLE|.
//
// Use |DSA_marshal_private_key| instead.
OPENSSL_EXPORT int i2d_DSAPrivateKey(const DSA *in, uint8_t **outp);
// d2i_DSAparams parses ASN.1, DER-encoded, DSA parameters from |len| bytes at
// |*inp|. If |out| is not NULL then, on exit, a pointer to the result is in
// |*out|. Note that, even if |*out| is already non-NULL on entry, it will not
// be written to. Rather, a fresh |DSA| is allocated and the previous one is
// freed. On successful exit, |*inp| is advanced past the DER structure. It
// returns the result or NULL on error.
// d2i_DSAparams parses a DER-encoded Dss-Parms structure (RFC 3279) from |len|
// bytes at |*inp|, as described in |d2i_SAMPLE|.
//
// Use |DSA_parse_parameters| instead.
OPENSSL_EXPORT DSA *d2i_DSAparams(DSA **out, const uint8_t **inp, long len);
// i2d_DSAparams marshals DSA parameters from |in| to an ASN.1, DER structure.
// If |outp| is not NULL then the result is written to |*outp| and |*outp| is
// advanced just past the output. It returns the number of bytes in the result,
// whether written or not, or a negative value on error.
// i2d_DSAparams marshals |in|'s parameters as a DER-encoded Dss-Parms structure
// (RFC 3279), as described in |i2d_SAMPLE|.
//
// Use |DSA_marshal_parameters| instead.
OPENSSL_EXPORT int i2d_DSAparams(const DSA *in, uint8_t **outp);

39
include/openssl/ec_key.h
Unescape View File

@ -294,43 +294,30 @@ struct ecdsa_method_st {
// EC_KEY_set_asn1_flag does nothing.
OPENSSL_EXPORT void EC_KEY_set_asn1_flag(EC_KEY *key, int flag);
// d2i_ECPrivateKey parses an ASN.1, DER-encoded, private key from |len| bytes
// at |*inp|. If |out_key| is not NULL then, on exit, a pointer to the result
// is in |*out_key|. Note that, even if |*out_key| is already non-NULL on entry,
// it * will not be written to. Rather, a fresh |EC_KEY| is allocated and the
// previous * one is freed. On successful exit, |*inp| is advanced past the DER
// structure. It returns the result or NULL on error.
//
// On input, if |*out_key| is non-NULL and has a group configured, the
// parameters field may be omitted but must match that group if present.
// d2i_ECPrivateKey parses a DER-encoded ECPrivateKey structure (RFC 5915) from
// |len| bytes at |*inp|, as described in |d2i_SAMPLE|. On input, if |*out_key|
// is non-NULL and has a group configured, the parameters field may be omitted
// but must match that group if present.
//
// Use |EC_KEY_parse_private_key| instead.
OPENSSL_EXPORT EC_KEY *d2i_ECPrivateKey(EC_KEY **out_key, const uint8_t **inp,
long len);
// i2d_ECPrivateKey marshals an EC private key from |key| to an ASN.1, DER
// structure. If |outp| is not NULL then the result is written to |*outp| and
// |*outp| is advanced just past the output. It returns the number of bytes in
// the result, whether written or not, or a negative value on error.
// i2d_ECPrivateKey marshals |key| as a DER-encoded ECPrivateKey structure (RFC
// 5915), as described in |i2d_SAMPLE|.
//
// Use |EC_KEY_marshal_private_key| instead.
OPENSSL_EXPORT int i2d_ECPrivateKey(const EC_KEY *key, uint8_t **outp);
// d2i_ECParameters parses an ASN.1, DER-encoded, set of EC parameters from
// |len| bytes at |*inp|. If |out_key| is not NULL then, on exit, a pointer to
// the result is in |*out_key|. Note that, even if |*out_key| is already
// non-NULL on entry, it will not be written to. Rather, a fresh |EC_KEY| is
// allocated and the previous one is freed. On successful exit, |*inp| is
// advanced past the DER structure. It returns the result or NULL on error.
// d2i_ECParameters parses a DER-encoded ECParameters structure (RFC 5480) from
// |len| bytes at |*inp|, as described in |d2i_SAMPLE|.
//
// Use |EC_KEY_parse_parameters| or |EC_KEY_parse_curve_name| instead.
OPENSSL_EXPORT EC_KEY *d2i_ECParameters(EC_KEY **out_key, const uint8_t **inp,
long len);
// i2d_ECParameters marshals EC parameters from |key| to an ASN.1, DER
// structure. If |outp| is not NULL then the result is written to |*outp| and
// |*outp| is advanced just past the output. It returns the number of bytes in
// the result, whether written or not, or a negative value on error.
// i2d_ECParameters marshals |key|'s parameters as a DER-encoded OBJECT
// IDENTIFIER, as described in |i2d_SAMPLE|.
//
// Use |EC_KEY_marshal_curve_name| instead.
OPENSSL_EXPORT int i2d_ECParameters(const EC_KEY *key, uint8_t **outp);
@ -344,10 +331,8 @@ OPENSSL_EXPORT int i2d_ECParameters(const EC_KEY *key, uint8_t **outp);
OPENSSL_EXPORT EC_KEY *o2i_ECPublicKey(EC_KEY **out_key, const uint8_t **inp,
long len);
// i2o_ECPublicKey marshals an EC point from |key|. If |outp| is not NULL then
// the result is written to |*outp| and |*outp| is advanced just past the
// output. It returns the number of bytes in the result, whether written or
// not, or a negative value on error.
// i2o_ECPublicKey marshals an EC point from |key|, as described in
// |i2d_SAMPLE|.
//
// Use |EC_POINT_point2cbb| instead.
OPENSSL_EXPORT int i2o_ECPublicKey(const EC_KEY *key, unsigned char **outp);

18
include/openssl/ecdsa.h
Unescape View File

@ -197,19 +197,17 @@ ECDSA_sign_with_nonce_and_leak_private_key_for_testing(const uint8_t *digest,
// Deprecated functions.
// d2i_ECDSA_SIG parses an ASN.1, DER-encoded, signature from |len| bytes at
// |*inp|. If |out| is not NULL then, on exit, a pointer to the result is in
// |*out|. Note that, even if |*out| is already non-NULL on entry, it will not
// be written to. Rather, a fresh |ECDSA_SIG| is allocated and the previous one
// is freed. On successful exit, |*inp| is advanced past the DER structure. It
// returns the result or NULL on error.
// d2i_ECDSA_SIG parses aa DER-encoded ECDSA-Sig-Value structure from |len|
// bytes at |*inp|, as described in |d2i_SAMPLE|.
//
// Use |ECDSA_SIG_parse| instead.
OPENSSL_EXPORT ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **out, const uint8_t **inp,
long len);
// i2d_ECDSA_SIG marshals a signature from |sig| to an ASN.1, DER
// structure. If |outp| is not NULL then the result is written to |*outp| and
// |*outp| is advanced just past the output. It returns the number of bytes in
// the result, whether written or not, or a negative value on error.
// i2d_ECDSA_SIG marshals |sig| as a DER-encoded ECDSA-Sig-Value, as described
// in |i2d_SAMPLE|.
//
// Use |ECDSA_SIG_marshal| instead.
OPENSSL_EXPORT int i2d_ECDSA_SIG(const ECDSA_SIG *sig, uint8_t **outp);

84
include/openssl/evp.h
Unescape View File

@ -873,34 +873,27 @@ OPENSSL_EXPORT void EVP_MD_do_all(void (*callback)(const EVP_MD *cipher,
void *arg),
void *arg);
// i2d_PrivateKey marshals a private key from |key| to an ASN.1, DER
// structure. If |outp| is not NULL then the result is written to |*outp| and
// |*outp| is advanced just past the output. It returns the number of bytes in
// the result, whether written or not, or a negative value on error.
// i2d_PrivateKey marshals a private key from |key| to type-specific format, as
// described in |i2d_SAMPLE|.
//
// RSA keys are serialized as a DER-encoded RSAPublicKey (RFC 3447) structure.
// RSA keys are serialized as a DER-encoded RSAPublicKey (RFC 8017) structure.
// EC keys are serialized as a DER-encoded ECPrivateKey (RFC 5915) structure.
//
// Use |RSA_marshal_private_key| or |EC_KEY_marshal_private_key| instead.
OPENSSL_EXPORT int i2d_PrivateKey(const EVP_PKEY *key, uint8_t **outp);
// i2d_PublicKey marshals a public key from |key| to a type-specific format.
// If |outp| is not NULL then the result is written to |*outp| and
// |*outp| is advanced just past the output. It returns the number of bytes in
// the result, whether written or not, or a negative value on error.
// i2d_PublicKey marshals a public key from |key| to a type-specific format, as
// described in |i2d_SAMPLE|.
//
// RSA keys are serialized as a DER-encoded RSAPublicKey (RFC 3447) structure.
// RSA keys are serialized as a DER-encoded RSAPublicKey (RFC 8017) structure.
// EC keys are serialized as an EC point per SEC 1.
//
// Use |RSA_marshal_public_key| or |EC_POINT_point2cbb| instead.
OPENSSL_EXPORT int i2d_PublicKey(const EVP_PKEY *key, uint8_t **outp);
// d2i_PrivateKey parses an ASN.1, DER-encoded, private key from |len| bytes at
// |*inp|. If |out| is not NULL then, on exit, a pointer to the result is in
// |*out|. Note that, even if |*out| is already non-NULL on entry, it will not
// be written to. Rather, a fresh |EVP_PKEY| is allocated and the previous one
// is freed. On successful exit, |*inp| is advanced past the DER structure. It
// returns the result or NULL on error.
// d2i_PrivateKey parses a DER-encoded private key from |len| bytes at |*inp|,
// as described in |d2i_SAMPLE|. The private key must have type |type|,
// otherwise it will be rejected.
//
// This function tries to detect one of several formats. Instead, use
// |EVP_parse_private_key| for a PrivateKeyInfo, |RSA_parse_private_key| for an
@ -917,15 +910,12 @@ OPENSSL_EXPORT EVP_PKEY *d2i_PrivateKey(int type, EVP_PKEY **out,
OPENSSL_EXPORT EVP_PKEY *d2i_AutoPrivateKey(EVP_PKEY **out, const uint8_t **inp,
long len);
// d2i_PublicKey parse a public key from |len| bytes at |*inp| in a type-
// specific format specified by |type|. If |out| is not NULL then, on exit, a
// pointer to the result is in |*out|. Note that, even if |*out| is already non-
// NULL on entry, it will not be written to. Rather, a fresh |EVP_PKEY| is
// allocated and the previous one is freed. On successful exit, |*inp| is
// advanced past the decoded key. It returns the result or NULL on error.
// d2i_PublicKey parses a public key from |len| bytes at |*inp| in a type-
// specific format specified by |type|, as described in |d2i_SAMPLE|.
//
// RSA keys are parsed as a DER-encoded RSAPublicKey (RFC 3447) structure.
// Parsing EC keys is not supported by this function.
// The only supported value for |type| is |EVP_PKEY_RSA|, which parses a
// DER-encoded RSAPublicKey (RFC 8017) structure. Parsing EC keys is not
// supported by this function.
//
// Use |RSA_parse_public_key| instead.
OPENSSL_EXPORT EVP_PKEY *d2i_PublicKey(int type, EVP_PKEY **out,
@ -974,70 +964,54 @@ OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(EVP_PKEY_CTX *ctx,
OPENSSL_EXPORT int EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(EVP_PKEY_CTX *ctx,
const EVP_MD *md);
// i2d_PUBKEY marshals a public key from |pkey| as a DER-encoded
// SubjectPublicKeyInfo. If |outp| is not NULL, the result is written to |*outp|
// and |*outp| is advanced just past the output. It returns the number of bytes
// in the result, whether written or not, or a negative value on error.
// i2d_PUBKEY marshals |pkey| as a DER-encoded SubjectPublicKeyInfo, as
// described in |i2d_SAMPLE|.
//
// Use |EVP_marshal_public_key| instead.
OPENSSL_EXPORT int i2d_PUBKEY(const EVP_PKEY *pkey, uint8_t **outp);
// d2i_PUBKEY parses a DER-encoded SubjectPublicKeyInfo from |len| bytes at
// |*inp|. It returns a newly-allocated result, or NULL on error. On success,
// |*inp| is advanced past the DER structure. If |out| is not NULL, it also
// frees any existing object pointed by |*out| and writes the result.
// |*inp|, as described in |d2i_SAMPLE|.
//
// Use |EVP_parse_public_key| instead.
OPENSSL_EXPORT EVP_PKEY *d2i_PUBKEY(EVP_PKEY **out, const uint8_t **inp,
long len);
// i2d_RSA_PUBKEY marshals |rsa| as a DER-encoded SubjectPublicKeyInfo. If
// |outp| is not NULL, the result is written to |*outp| and
// |*outp| is advanced just past the output. It returns the number of bytes in
// the result, whether written or not, or a negative value on error.
// i2d_RSA_PUBKEY marshals |rsa| as a DER-encoded SubjectPublicKeyInfo
// structure, as described in |i2d_SAMPLE|.
//
// Use |EVP_marshal_public_key| instead.
OPENSSL_EXPORT int i2d_RSA_PUBKEY(const RSA *rsa, uint8_t **outp);
// d2i_RSA_PUBKEY parses an RSA public key as a DER-encoded SubjectPublicKeyInfo
// from |len| bytes at |*inp|. It returns a newly-allocated result, or NULL on
// error. On success, |*inp| is advanced past the DER structure. If |out| is not
// NULL, it also frees any existing object pointed by |*out| and writes the
// result.
// from |len| bytes at |*inp|, as described in |d2i_SAMPLE|.
// SubjectPublicKeyInfo structures containing other key types are rejected.
//
// Use |EVP_parse_public_key| instead.
OPENSSL_EXPORT RSA *d2i_RSA_PUBKEY(RSA **out, const uint8_t **inp, long len);
// i2d_DSA_PUBKEY marshals |dsa| as a DER-encoded SubjectPublicKeyInfo. If
// |outp| is not NULL, the result is written to |*outp| and |*outp| is advanced
// just past the output. It returns the number of bytes in the result, whether
// written or not, or a negative value on error.
// i2d_DSA_PUBKEY marshals |dsa| as a DER-encoded SubjectPublicKeyInfo, as
// described in |i2d_SAMPLE|.
//
// Use |EVP_marshal_public_key| instead.
OPENSSL_EXPORT int i2d_DSA_PUBKEY(const DSA *dsa, uint8_t **outp);
// d2i_DSA_PUBKEY parses a DSA public key as a DER-encoded SubjectPublicKeyInfo
// from |len| bytes at |*inp|. It returns a newly-allocated result, or NULL on
// error. On success, |*inp| is advanced past the DER structure. If |out| is not
// NULL, it also frees any existing object pointed by |*out| and writes the
// result.
// from |len| bytes at |*inp|, as described in |d2i_SAMPLE|.
// SubjectPublicKeyInfo structures containing other key types are rejected.
//
// Use |EVP_parse_public_key| instead.
OPENSSL_EXPORT DSA *d2i_DSA_PUBKEY(DSA **out, const uint8_t **inp, long len);
// i2d_EC_PUBKEY marshals |ec_key| as a DER-encoded SubjectPublicKeyInfo. If
// |outp| is not NULL, the result is written to |*outp| and |*outp| is advanced
// just past the output. It returns the number of bytes in the result, whether
// written or not, or a negative value on error.
// i2d_EC_PUBKEY marshals |ec_key| as a DER-encoded SubjectPublicKeyInfo, as
// described in |i2d_SAMPLE|.
//
// Use |EVP_marshal_public_key| instead.
OPENSSL_EXPORT int i2d_EC_PUBKEY(const EC_KEY *ec_key, uint8_t **outp);
// d2i_EC_PUBKEY parses an EC public key as a DER-encoded SubjectPublicKeyInfo
// from |len| bytes at |*inp|. It returns a newly-allocated result, or NULL on
// error. On success, |*inp| is advanced past the DER structure. If |out| is not
// NULL, it also frees any existing object pointed by |*out| and writes the
// result.
// from |len| bytes at |*inp|, as described in |d2i_SAMPLE|.
// SubjectPublicKeyInfo structures containing other key types are rejected.
//
// Use |EVP_parse_public_key| instead.
OPENSSL_EXPORT EC_KEY *d2i_EC_PUBKEY(EC_KEY **out, const uint8_t **inp,

12
include/openssl/pkcs7.h
Unescape View File

@ -137,11 +137,7 @@ typedef struct {
} PKCS7;
// d2i_PKCS7 parses a BER-encoded, PKCS#7 signed data ContentInfo structure from
// |len| bytes at |*inp|. If |out| is not NULL then, on exit, a pointer to the
// result is in |*out|. Note that, even if |*out| is already non-NULL on entry,
// it will not be written to. Rather, a fresh |PKCS7| is allocated and the
// previous one is freed. On successful exit, |*inp| is advanced past the BER
// structure. It returns the result or NULL on error.
// |len| bytes at |*inp|, as described in |d2i_SAMPLE|.
OPENSSL_EXPORT PKCS7 *d2i_PKCS7(PKCS7 **out, const uint8_t **inp,
size_t len);
@ -152,10 +148,8 @@ OPENSSL_EXPORT PKCS7 *d2i_PKCS7(PKCS7 **out, const uint8_t **inp,
// from |bio|.
OPENSSL_EXPORT PKCS7 *d2i_PKCS7_bio(BIO *bio, PKCS7 **out);
// i2d_PKCS7 is a dummy function which copies the contents of |p7|. If |out| is
// not NULL then the result is written to |*out| and |*out| is advanced just
// past the output. It returns the number of bytes in the result, whether
// written or not, or a negative value on error.
// i2d_PKCS7 marshals |p7| as a DER-encoded PKCS#7 ContentInfo structure, as
// described in |i2d_SAMPLE|.
OPENSSL_EXPORT int i2d_PKCS7(const PKCS7 *p7, uint8_t **out);
// i2d_PKCS7_bio writes |p7| to |bio|. It returns one on success and zero on

52
include/openssl/rsa.h
Unescape View File

@ -526,44 +526,44 @@ OPENSSL_EXPORT int RSA_add_pkcs1_prefix(uint8_t **out_msg, size_t *out_msg_len,
// ASN.1 functions.
// RSA_parse_public_key parses a DER-encoded RSAPublicKey structure (RFC 3447)
// RSA_parse_public_key parses a DER-encoded RSAPublicKey structure (RFC 8017)
// from |cbs| and advances |cbs|. It returns a newly-allocated |RSA| or NULL on
// error.
OPENSSL_EXPORT RSA *RSA_parse_public_key(CBS *cbs);
// RSA_public_key_from_bytes parses |in| as a DER-encoded RSAPublicKey structure
// (RFC 3447). It returns a newly-allocated |RSA| or NULL on error.
// (RFC 8017). It returns a newly-allocated |RSA| or NULL on error.
OPENSSL_EXPORT RSA *RSA_public_key_from_bytes(const uint8_t *in, size_t in_len);
// RSA_marshal_public_key marshals |rsa| as a DER-encoded RSAPublicKey structure
// (RFC 3447) and appends the result to |cbb|. It returns one on success and
// (RFC 8017) and appends the result to |cbb|. It returns one on success and
// zero on failure.
OPENSSL_EXPORT int RSA_marshal_public_key(CBB *cbb, const RSA *rsa);
// RSA_public_key_to_bytes marshals |rsa| as a DER-encoded RSAPublicKey
// structure (RFC 3447) and, on success, sets |*out_bytes| to a newly allocated
// structure (RFC 8017) and, on success, sets |*out_bytes| to a newly allocated
// buffer containing the result and returns one. Otherwise, it returns zero. The
// result should be freed with |OPENSSL_free|.
OPENSSL_EXPORT int RSA_public_key_to_bytes(uint8_t **out_bytes, size_t *out_len,
const RSA *rsa);
// RSA_parse_private_key parses a DER-encoded RSAPrivateKey structure (RFC 3447)
// RSA_parse_private_key parses a DER-encoded RSAPrivateKey structure (RFC 8017)
// from |cbs| and advances |cbs|. It returns a newly-allocated |RSA| or NULL on
// error.
OPENSSL_EXPORT RSA *RSA_parse_private_key(CBS *cbs);
// RSA_private_key_from_bytes parses |in| as a DER-encoded RSAPrivateKey
// structure (RFC 3447). It returns a newly-allocated |RSA| or NULL on error.
// structure (RFC 8017). It returns a newly-allocated |RSA| or NULL on error.
OPENSSL_EXPORT RSA *RSA_private_key_from_bytes(const uint8_t *in,
size_t in_len);
// RSA_marshal_private_key marshals |rsa| as a DER-encoded RSAPrivateKey
// structure (RFC 3447) and appends the result to |cbb|. It returns one on
// structure (RFC 8017) and appends the result to |cbb|. It returns one on
// success and zero on failure.
OPENSSL_EXPORT int RSA_marshal_private_key(CBB *cbb, const RSA *rsa);
// RSA_private_key_to_bytes marshals |rsa| as a DER-encoded RSAPrivateKey
// structure (RFC 3447) and, on success, sets |*out_bytes| to a newly allocated
// structure (RFC 8017) and, on success, sets |*out_bytes| to a newly allocated
// buffer containing the result and returns one. Otherwise, it returns zero. The
// result should be freed with |OPENSSL_free|.
OPENSSL_EXPORT int RSA_private_key_to_bytes(uint8_t **out_bytes,
@ -625,32 +625,28 @@ OPENSSL_EXPORT int RSA_blinding_on(RSA *rsa, BN_CTX *ctx);
OPENSSL_EXPORT RSA *RSA_generate_key(int bits, unsigned long e, void *callback,
void *cb_arg);
// d2i_RSAPublicKey parses an ASN.1, DER-encoded, RSA public key from |len|
// bytes at |*inp|. If |out| is not NULL then, on exit, a pointer to the result
// is in |*out|. Note that, even if |*out| is already non-NULL on entry, it
// will not be written to. Rather, a fresh |RSA| is allocated and the previous
// one is freed. On successful exit, |*inp| is advanced past the DER structure.
// It returns the result or NULL on error.
// d2i_RSAPublicKey parses a DER-encoded RSAPublicKey structure (RFC 8017) from
// |len| bytes at |*inp|, as described in |d2i_SAMPLE|.
//
// Use |RSA_parse_public_key| instead.
OPENSSL_EXPORT RSA *d2i_RSAPublicKey(RSA **out, const uint8_t **inp, long len);
// i2d_RSAPublicKey marshals |in| to an ASN.1, DER structure. If |outp| is not
// NULL then the result is written to |*outp| and |*outp| is advanced just past
// the output. It returns the number of bytes in the result, whether written or
// not, or a negative value on error.
// i2d_RSAPublicKey marshals |in| to a DER-encoded RSAPublicKey structure (RFC
// 8017), as described in |i2d_SAMPLE|.
//
// Use |RSA_marshal_public_key| instead.
OPENSSL_EXPORT int i2d_RSAPublicKey(const RSA *in, uint8_t **outp);
// d2i_RSAPrivateKey parses an ASN.1, DER-encoded, RSA private key from |len|
// bytes at |*inp|. If |out| is not NULL then, on exit, a pointer to the result
// is in |*out|. Note that, even if |*out| is already non-NULL on entry, it
// will not be written to. Rather, a fresh |RSA| is allocated and the previous
// one is freed. On successful exit, |*inp| is advanced past the DER structure.
// It returns the result or NULL on error.
// d2i_RSAPrivateKey parses a DER-encoded RSAPrivateKey structure (RFC 8017)
// from |len| bytes at |*inp|, as described in |d2i_SAMPLE|.
//
// Use |RSA_parse_private_key| instead.
OPENSSL_EXPORT RSA *d2i_RSAPrivateKey(RSA **out, const uint8_t **inp, long len);
// i2d_RSAPrivateKey marshals |in| to an ASN.1, DER structure. If |outp| is not
// NULL then the result is written to |*outp| and |*outp| is advanced just past
// the output. It returns the number of bytes in the result, whether written or
// not, or a negative value on error.
// i2d_RSAPrivateKey marshals |in| to a DER-encoded RSAPrivateKey structure (RFC
// 8017), as described in |i2d_SAMPLE|.
//
// Use |RSA_marshal_private_key| instead.
OPENSSL_EXPORT int i2d_RSAPrivateKey(const RSA *in, uint8_t **outp);
// RSA_padding_add_PKCS1_PSS acts like |RSA_padding_add_PKCS1_PSS_mgf1| but the

11
include/openssl/ssl.h
Unescape View File

@ -4575,20 +4575,13 @@ OPENSSL_EXPORT int SSL_get_shared_sigalgs(SSL *ssl, int idx, int *psign,
// SSL_MODE_HANDSHAKE_CUTTHROUGH is the same as SSL_MODE_ENABLE_FALSE_START.
#define SSL_MODE_HANDSHAKE_CUTTHROUGH SSL_MODE_ENABLE_FALSE_START
// i2d_SSL_SESSION serializes |in| to the bytes pointed to by |*pp|. On success,
// it returns the number of bytes written and advances |*pp| by that many bytes.
// On failure, it returns -1. If |pp| is NULL, no bytes are written and only the
// length is returned.
// i2d_SSL_SESSION serializes |in|, as described in |i2d_SAMPLE|.
//
// Use |SSL_SESSION_to_bytes| instead.
OPENSSL_EXPORT int i2d_SSL_SESSION(SSL_SESSION *in, uint8_t **pp);
// d2i_SSL_SESSION parses a serialized session from the |length| bytes pointed
// to by |*pp|. It returns the new |SSL_SESSION| and advances |*pp| by the
// number of bytes consumed on success and NULL on failure. The caller takes
// ownership of the new session and must call |SSL_SESSION_free| when done.
//
// If |a| is non-NULL, |*a| is released and set the new |SSL_SESSION|.
// to by |*pp|, as described in |d2i_SAMPLE|.
//
// Use |SSL_SESSION_from_bytes| instead.
OPENSSL_EXPORT SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const uint8_t **pp,

48
include/openssl/x509.h
Unescape View File

@ -885,28 +885,16 @@ OPENSSL_EXPORT int i2d_X509_AUX(X509 *a, unsigned char **pp);
OPENSSL_EXPORT X509 *d2i_X509_AUX(X509 **a, const unsigned char **pp,
long length);
// i2d_re_X509_tbs serializes the TBSCertificate portion of |x509|. If |outp| is
// NULL, nothing is written. Otherwise, if |*outp| is not NULL, the result is
// written to |*outp|, which must have enough space available, and |*outp| is
// advanced just past the output. If |outp| is non-NULL and |*outp| is NULL, it
// sets |*outp| to a newly-allocated buffer containing the result. The caller is
// responsible for releasing the buffer with |OPENSSL_free|. In all cases, this
// function returns the number of bytes in the result, whether written or not,
// or a negative value on error.
// i2d_re_X509_tbs serializes the TBSCertificate portion of |x509|, as described
// in |i2d_SAMPLE|.
//
// This function re-encodes the TBSCertificate and may not reflect |x509|'s
// original encoding. It may be used to manually generate a signature for a new
// certificate. To verify certificates, use |i2d_X509_tbs| instead.
OPENSSL_EXPORT int i2d_re_X509_tbs(X509 *x509, unsigned char **outp);
// i2d_X509_tbs serializes the TBSCertificate portion of |x509|. If |outp| is
// NULL, nothing is written. Otherwise, if |*outp| is not NULL, the result is
// written to |*outp|, which must have enough space available, and |*outp| is
// advanced just past the output. If |outp| is non-NULL and |*outp| is NULL, it
// sets |*outp| to a newly-allocated buffer containing the result. The caller is
// responsible for releasing the buffer with |OPENSSL_free|. In all cases, this
// function returns the number of bytes in the result, whether written or not,
// or a negative value on error.
// i2d_X509_tbs serializes the TBSCertificate portion of |x509|, as described in
// |i2d_SAMPLE|.
//
// This function preserves the original encoding of the TBSCertificate and may
// not reflect modifications made to |x509|. It may be used to manually verify
@ -1073,13 +1061,7 @@ OPENSSL_EXPORT void X509_REQ_get0_signature(const X509_REQ *req,
OPENSSL_EXPORT int X509_REQ_get_signature_nid(const X509_REQ *req);
// i2d_re_X509_REQ_tbs serializes the CertificationRequestInfo (see RFC 2986)
// portion of |req|. If |outp| is NULL, nothing is written. Otherwise, if
// |*outp| is not NULL, the result is written to |*outp|, which must have enough
// space available, and |*outp| is advanced just past the output. If |outp| is
// non-NULL and |*outp| is NULL, it sets |*outp| to a newly-allocated buffer
// containing the result. The caller is responsible for releasing the buffer
// with |OPENSSL_free|. In all cases, this function returns the number of bytes
// in the result, whether written or not, or a negative value on error.
// portion of |req|, as described in |i2d_SAMPLE|.
//
// This function re-encodes the CertificationRequestInfo and may not reflect
// |req|'s original encoding. It may be used to manually generate a signature
@ -1217,28 +1199,16 @@ OPENSSL_EXPORT void X509_CRL_get0_signature(const X509_CRL *crl,
// a known NID.
OPENSSL_EXPORT int X509_CRL_get_signature_nid(const X509_CRL *crl);
// i2d_re_X509_CRL_tbs serializes the TBSCertList portion of |crl|. If |outp| is
// NULL, nothing is written. Otherwise, if |*outp| is not NULL, the result is
// written to |*outp|, which must have enough space available, and |*outp| is
// advanced just past the output. If |outp| is non-NULL and |*outp| is NULL, it
// sets |*outp| to a newly-allocated buffer containing the result. The caller is
// responsible for releasing the buffer with |OPENSSL_free|. In all cases, this
// function returns the number of bytes in the result, whether written or not,
// or a negative value on error.
// i2d_re_X509_CRL_tbs serializes the TBSCertList portion of |crl|, as described
// in |i2d_SAMPLE|.
//
// This function re-encodes the TBSCertList and may not reflect |crl|'s original
// encoding. It may be used to manually generate a signature for a new CRL. To
// verify CRLs, use |i2d_X509_CRL_tbs| instead.
OPENSSL_EXPORT int i2d_re_X509_CRL_tbs(X509_CRL *crl, unsigned char **outp);
// i2d_X509_CRL_tbs serializes the TBSCertList portion of |crl|. If |outp| is
// NULL, nothing is written. Otherwise, if |*outp| is not NULL, the result is
// written to |*outp|, which must have enough space available, and |*outp| is
// advanced just past the output. If |outp| is non-NULL and |*outp| is NULL, it
// sets |*outp| to a newly-allocated buffer containing the result. The caller is
// responsible for releasing the buffer with |OPENSSL_free|. In all cases, this
// function returns the number of bytes in the result, whether written or not,
// or a negative value on error.
// i2d_X509_CRL_tbs serializes the TBSCertList portion of |crl|, as described in
// |i2d_SAMPLE|.
//
// This function preserves the original encoding of the TBSCertList and may not
// reflect modifications made to |crl|. It may be used to manually verify the

Write Preview
Loading…
Cancel
Save