diff options
Diffstat (limited to 'secure/lib/libcrypto/man/d2i_X509.3')
| -rw-r--r-- | secure/lib/libcrypto/man/d2i_X509.3 | 306 |
1 files changed, 137 insertions, 169 deletions
diff --git a/secure/lib/libcrypto/man/d2i_X509.3 b/secure/lib/libcrypto/man/d2i_X509.3 index e08c629c11a2..dcfd42bf6672 100644 --- a/secure/lib/libcrypto/man/d2i_X509.3 +++ b/secure/lib/libcrypto/man/d2i_X509.3 @@ -128,189 +128,178 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "d2i_X509 3" -.TH d2i_X509 3 "2018-08-14" "1.0.2p" "OpenSSL" +.IX Title "D2I_X509 3" +.TH D2I_X509 3 "2018-09-11" "1.1.1" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" -d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio, -i2d_X509_fp \- X509 encode and decode functions +d2i_ACCESS_DESCRIPTION, d2i_ADMISSIONS, d2i_ADMISSION_SYNTAX, d2i_ASIdOrRange, d2i_ASIdentifierChoice, d2i_ASIdentifiers, d2i_ASN1_BIT_STRING, d2i_ASN1_BMPSTRING, d2i_ASN1_ENUMERATED, d2i_ASN1_GENERALIZEDTIME, d2i_ASN1_GENERALSTRING, d2i_ASN1_IA5STRING, d2i_ASN1_INTEGER, d2i_ASN1_NULL, d2i_ASN1_OBJECT, d2i_ASN1_OCTET_STRING, d2i_ASN1_PRINTABLE, d2i_ASN1_PRINTABLESTRING, d2i_ASN1_SEQUENCE_ANY, d2i_ASN1_SET_ANY, d2i_ASN1_T61STRING, d2i_ASN1_TIME, d2i_ASN1_TYPE, d2i_ASN1_UINTEGER, d2i_ASN1_UNIVERSALSTRING, d2i_ASN1_UTCTIME, d2i_ASN1_UTF8STRING, d2i_ASN1_VISIBLESTRING, d2i_ASRange, d2i_AUTHORITY_INFO_ACCESS, d2i_AUTHORITY_KEYID, d2i_BASIC_CONSTRAINTS, d2i_CERTIFICATEPOLICIES, d2i_CMS_ContentInfo, d2i_CMS_ReceiptRequest, d2i_CMS_bio, d2i_CRL_DIST_POINTS, d2i_DHxparams, d2i_DIRECTORYSTRING, d2i_DISPLAYTEXT, d2i_DIST_POINT, d2i_DIST_POINT_NAME, d2i_DSAPrivateKey, d2i_DSAPrivateKey_bio, d2i_DSAPrivateKey_fp, d2i_DSAPublicKey, d2i_DSA_PUBKEY, d2i_DSA_PUBKEY_bio, d2i_DSA_PUBKEY_fp, d2i_DSA_SIG, d2i_DSAparams, d2i_ECPKParameters, d2i_ECParameters, d2i_ECPrivateKey, d2i_ECPrivateKey_bio, d2i_ECPrivateKey_fp, d2i_EC_PUBKEY, d2i_EC_PUBKEY_bio, d2i_EC_PUBKEY_fp, d2i_EDIPARTYNAME, d2i_ESS_CERT_ID, d2i_ESS_ISSUER_SERIAL, d2i_ESS_SIGNING_CERT, d2i_EXTENDED_KEY_USAGE, d2i_GENERAL_NAME, d2i_GENERAL_NAMES, d2i_IPAddressChoice, d2i_IPAddressFamily, d2i_IPAddressOrRange, d2i_IPAddressRange, d2i_ISSUING_DIST_POINT, d2i_NAMING_AUTHORITY, d2i_NETSCAPE_CERT_SEQUENCE, d2i_NETSCAPE_SPKAC, d2i_NETSCAPE_SPKI, d2i_NOTICEREF, d2i_OCSP_BASICRESP, d2i_OCSP_CERTID, d2i_OCSP_CERTSTATUS, d2i_OCSP_CRLID, d2i_OCSP_ONEREQ, d2i_OCSP_REQINFO, d2i_OCSP_REQUEST, d2i_OCSP_RESPBYTES, d2i_OCSP_RESPDATA, d2i_OCSP_RESPID, d2i_OCSP_RESPONSE, d2i_OCSP_REVOKEDINFO, d2i_OCSP_SERVICELOC, d2i_OCSP_SIGNATURE, d2i_OCSP_SINGLERESP, d2i_OTHERNAME, d2i_PBE2PARAM, d2i_PBEPARAM, d2i_PBKDF2PARAM, d2i_PKCS12, d2i_PKCS12_BAGS, d2i_PKCS12_MAC_DATA, d2i_PKCS12_SAFEBAG, d2i_PKCS12_bio, d2i_PKCS12_fp, d2i_PKCS7, d2i_PKCS7_DIGEST, d2i_PKCS7_ENCRYPT, d2i_PKCS7_ENC_CONTENT, d2i_PKCS7_ENVELOPE, d2i_PKCS7_ISSUER_AND_SERIAL, d2i_PKCS7_RECIP_INFO, d2i_PKCS7_SIGNED, d2i_PKCS7_SIGNER_INFO, d2i_PKCS7_SIGN_ENVELOPE, d2i_PKCS7_bio, d2i_PKCS7_fp, d2i_PKCS8_PRIV_KEY_INFO, d2i_PKCS8_PRIV_KEY_INFO_bio, d2i_PKCS8_PRIV_KEY_INFO_fp, d2i_PKCS8_bio, d2i_PKCS8_fp, d2i_PKEY_USAGE_PERIOD, d2i_POLICYINFO, d2i_POLICYQUALINFO, d2i_PROFESSION_INFO, d2i_PROXY_CERT_INFO_EXTENSION, d2i_PROXY_POLICY, d2i_RSAPrivateKey, d2i_RSAPrivateKey_bio, d2i_RSAPrivateKey_fp, d2i_RSAPublicKey, d2i_RSAPublicKey_bio, d2i_RSAPublicKey_fp, d2i_RSA_OAEP_PARAMS, d2i_RSA_PSS_PARAMS, d2i_RSA_PUBKEY, d2i_RSA_PUBKEY_bio, d2i_RSA_PUBKEY_fp, d2i_SCRYPT_PARAMS, d2i_SCT_LIST, d2i_SXNET, d2i_SXNETID, d2i_TS_ACCURACY, d2i_TS_MSG_IMPRINT, d2i_TS_MSG_IMPRINT_bio, d2i_TS_MSG_IMPRINT_fp, d2i_TS_REQ, d2i_TS_REQ_bio, d2i_TS_REQ_fp, d2i_TS_RESP, d2i_TS_RESP_bio, d2i_TS_RESP_fp, d2i_TS_STATUS_INFO, d2i_TS_TST_INFO, d2i_TS_TST_INFO_bio, d2i_TS_TST_INFO_fp, d2i_USERNOTICE, d2i_X509, d2i_X509_ALGOR, d2i_X509_ALGORS, d2i_X509_ATTRIBUTE, d2i_X509_CERT_AUX, d2i_X509_CINF, d2i_X509_CRL, d2i_X509_CRL_INFO, d2i_X509_CRL_bio, d2i_X509_CRL_fp, d2i_X509_EXTENSION, d2i_X509_EXTENSIONS, d2i_X509_NAME, d2i_X509_NAME_ENTRY, d2i_X509_PUBKEY, d2i_X509_REQ, d2i_X509_REQ_INFO, d2i_X509_REQ_bio, d2i_X509_REQ_fp, d2i_X509_REVOKED, d2i_X509_SIG, d2i_X509_VAL, i2d_ACCESS_DESCRIPTION, i2d_ADMISSIONS, i2d_ADMISSION_SYNTAX, i2d_ASIdOrRange, i2d_ASIdentifierChoice, i2d_ASIdentifiers, i2d_ASN1_BIT_STRING, i2d_ASN1_BMPSTRING, i2d_ASN1_ENUMERATED, i2d_ASN1_GENERALIZEDTIME, i2d_ASN1_GENERALSTRING, i2d_ASN1_IA5STRING, i2d_ASN1_INTEGER, i2d_ASN1_NULL, i2d_ASN1_OBJECT, i2d_ASN1_OCTET_STRING, i2d_ASN1_PRINTABLE, i2d_ASN1_PRINTABLESTRING, i2d_ASN1_SEQUENCE_ANY, i2d_ASN1_SET_ANY, i2d_ASN1_T61STRING, i2d_ASN1_TIME, i2d_ASN1_TYPE, i2d_ASN1_UNIVERSALSTRING, i2d_ASN1_UTCTIME, i2d_ASN1_UTF8STRING, i2d_ASN1_VISIBLESTRING, i2d_ASN1_bio_stream, i2d_ASRange, i2d_AUTHORITY_INFO_ACCESS, i2d_AUTHORITY_KEYID, i2d_BASIC_CONSTRAINTS, i2d_CERTIFICATEPOLICIES, i2d_CMS_ContentInfo, i2d_CMS_ReceiptRequest, i2d_CMS_bio, i2d_CRL_DIST_POINTS, i2d_DHxparams, i2d_DIRECTORYSTRING, i2d_DISPLAYTEXT, i2d_DIST_POINT, i2d_DIST_POINT_NAME, i2d_DSAPrivateKey, i2d_DSAPrivateKey_bio, i2d_DSAPrivateKey_fp, i2d_DSAPublicKey, i2d_DSA_PUBKEY, i2d_DSA_PUBKEY_bio, i2d_DSA_PUBKEY_fp, i2d_DSA_SIG, i2d_DSAparams, i2d_ECPKParameters, i2d_ECParameters, i2d_ECPrivateKey, i2d_ECPrivateKey_bio, i2d_ECPrivateKey_fp, i2d_EC_PUBKEY, i2d_EC_PUBKEY_bio, i2d_EC_PUBKEY_fp, i2d_EDIPARTYNAME, i2d_ESS_CERT_ID, i2d_ESS_ISSUER_SERIAL, i2d_ESS_SIGNING_CERT, i2d_EXTENDED_KEY_USAGE, i2d_GENERAL_NAME, i2d_GENERAL_NAMES, i2d_IPAddressChoice, i2d_IPAddressFamily, i2d_IPAddressOrRange, i2d_IPAddressRange, i2d_ISSUING_DIST_POINT, i2d_NAMING_AUTHORITY, i2d_NETSCAPE_CERT_SEQUENCE, i2d_NETSCAPE_SPKAC, i2d_NETSCAPE_SPKI, i2d_NOTICEREF, i2d_OCSP_BASICRESP, i2d_OCSP_CERTID, i2d_OCSP_CERTSTATUS, i2d_OCSP_CRLID, i2d_OCSP_ONEREQ, i2d_OCSP_REQINFO, i2d_OCSP_REQUEST, i2d_OCSP_RESPBYTES, i2d_OCSP_RESPDATA, i2d_OCSP_RESPID, i2d_OCSP_RESPONSE, i2d_OCSP_REVOKEDINFO, i2d_OCSP_SERVICELOC, i2d_OCSP_SIGNATURE, i2d_OCSP_SINGLERESP, i2d_OTHERNAME, i2d_PBE2PARAM, i2d_PBEPARAM, i2d_PBKDF2PARAM, i2d_PKCS12, i2d_PKCS12_BAGS, i2d_PKCS12_MAC_DATA, i2d_PKCS12_SAFEBAG, i2d_PKCS12_bio, i2d_PKCS12_fp, i2d_PKCS7, i2d_PKCS7_DIGEST, i2d_PKCS7_ENCRYPT, i2d_PKCS7_ENC_CONTENT, i2d_PKCS7_ENVELOPE, i2d_PKCS7_ISSUER_AND_SERIAL, i2d_PKCS7_NDEF, i2d_PKCS7_RECIP_INFO, i2d_PKCS7_SIGNED, i2d_PKCS7_SIGNER_INFO, i2d_PKCS7_SIGN_ENVELOPE, i2d_PKCS7_bio, i2d_PKCS7_fp, i2d_PKCS8PrivateKeyInfo_bio, i2d_PKCS8PrivateKeyInfo_fp, i2d_PKCS8_PRIV_KEY_INFO, i2d_PKCS8_PRIV_KEY_INFO_bio, i2d_PKCS8_PRIV_KEY_INFO_fp, i2d_PKCS8_bio, i2d_PKCS8_fp, i2d_PKEY_USAGE_PERIOD, i2d_POLICYINFO, i2d_POLICYQUALINFO, i2d_PROFESSION_INFO, i2d_PROXY_CERT_INFO_EXTENSION, i2d_PROXY_POLICY, i2d_PublicKey, i2d_RSAPrivateKey, i2d_RSAPrivateKey_bio, i2d_RSAPrivateKey_fp, i2d_RSAPublicKey, i2d_RSAPublicKey_bio, i2d_RSAPublicKey_fp, i2d_RSA_OAEP_PARAMS, i2d_RSA_PSS_PARAMS, i2d_RSA_PUBKEY, i2d_RSA_PUBKEY_bio, i2d_RSA_PUBKEY_fp, i2d_SCRYPT_PARAMS, i2d_SCT_LIST, i2d_SXNET, i2d_SXNETID, i2d_TS_ACCURACY, i2d_TS_MSG_IMPRINT, i2d_TS_MSG_IMPRINT_bio, i2d_TS_MSG_IMPRINT_fp, i2d_TS_REQ, i2d_TS_REQ_bio, i2d_TS_REQ_fp, i2d_TS_RESP, i2d_TS_RESP_bio, i2d_TS_RESP_fp, i2d_TS_STATUS_INFO, i2d_TS_TST_INFO, i2d_TS_TST_INFO_bio, i2d_TS_TST_INFO_fp, i2d_USERNOTICE, i2d_X509, i2d_X509_ALGOR, i2d_X509_ALGORS, i2d_X509_ATTRIBUTE, i2d_X509_CERT_AUX, i2d_X509_CINF, i2d_X509_CRL, i2d_X509_CRL_INFO, i2d_X509_CRL_bio, i2d_X509_CRL_fp, i2d_X509_EXTENSION, i2d_X509_EXTENSIONS, i2d_X509_NAME, i2d_X509_NAME_ENTRY, i2d_X509_PUBKEY, i2d_X509_REQ, i2d_X509_REQ_INFO, i2d_X509_REQ_bio, i2d_X509_REQ_fp, i2d_X509_REVOKED, i2d_X509_SIG, i2d_X509_VAL, \&\- convert objects from/to ASN.1/DER representation .SH "SYNOPSIS" .IX Header "SYNOPSIS" -.Vb 1 -\& #include <openssl/x509.h> -\& -\& X509 *d2i_X509(X509 **px, const unsigned char **in, long len); -\& X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len); -\& int i2d_X509(X509 *x, unsigned char **out); -\& int i2d_X509_AUX(X509 *x, unsigned char **out); -\& -\& X509 *d2i_X509_bio(BIO *bp, X509 **x); -\& X509 *d2i_X509_fp(FILE *fp, X509 **x); -\& -\& int i2d_X509_bio(BIO *bp, X509 *x); -\& int i2d_X509_fp(FILE *fp, X509 *x); +.Vb 3 +\& TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length); +\& TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a); +\& TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a); \& -\& int i2d_re_X509_tbs(X509 *x, unsigned char **out); +\& int i2d_TYPE(TYPE *a, unsigned char **ppout); +\& int i2d_TYPE_fp(FILE *fp, TYPE *a); +\& int i2d_TYPE_bio(BIO *bp, TYPE *a); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" -The X509 encode and decode routines encode and parse an -\&\fBX509\fR structure, which represents an X509 certificate. -.PP -\&\fId2i_X509()\fR attempts to decode \fBlen\fR bytes at \fB*in\fR. If -successful a pointer to the \fBX509\fR structure is returned. If an error -occurred then \fB\s-1NULL\s0\fR is returned. If \fBpx\fR is not \fB\s-1NULL\s0\fR then the -returned structure is written to \fB*px\fR. If \fB*px\fR is not \fB\s-1NULL\s0\fR -then it is assumed that \fB*px\fR contains a valid \fBX509\fR -structure and an attempt is made to reuse it. This \*(L"reuse\*(R" capability is present -for historical compatibility but its use is \fBstrongly discouraged\fR (see \s-1BUGS\s0 -below, and the discussion in the \s-1RETURN VALUES\s0 section). -.PP -If the call is successful \fB*in\fR is incremented to the byte following the -parsed data. +In the description here, \fI\s-1TYPE\s0\fR is used a placeholder +for any of the OpenSSL datatypes, such as \fIX509_CRL\fR. +The function parameters \fIppin\fR and \fIppout\fR are generally +either both named \fIpp\fR in the headers, or \fIin\fR and \fIout\fR. +.PP +These functions convert OpenSSL objects to and from their \s-1ASN.1/DER\s0 +encoding. Unlike the C structures which can have pointers to sub-objects +within, the \s-1DER\s0 is a serialized encoding, suitable for sending over the +network, writing to a file, and so on. +.PP +\&\fId2i_TYPE()\fR attempts to decode \fBlen\fR bytes at \fB*ppin\fR. If successful a +pointer to the \fB\s-1TYPE\s0\fR structure is returned and \fB*ppin\fR is incremented to +the byte following the parsed data. If \fBa\fR is not \fB\s-1NULL\s0\fR then a pointer +to the returned structure is also written to \fB*a\fR. If an error occurred +then \fB\s-1NULL\s0\fR is returned. +.PP +On a successful return, if \fB*a\fR is not \fB\s-1NULL\s0\fR then it is assumed that \fB*a\fR +contains a valid \fB\s-1TYPE\s0\fR structure and an attempt is made to reuse it. This +\&\*(L"reuse\*(R" capability is present for historical compatibility but its use is +\&\fBstrongly discouraged\fR (see \s-1BUGS\s0 below, and the discussion in the \s-1RETURN +VALUES\s0 section). +.PP +\&\fId2i_TYPE_bio()\fR is similar to \fId2i_TYPE()\fR except it attempts +to parse data from \s-1BIO\s0 \fBbp\fR. .PP -\&\fId2i_X509_AUX()\fR is similar to \fId2i_X509()\fR but the input is expected to consist of -an X509 certificate followed by auxiliary trust information. -This is used by the \s-1PEM\s0 routines to read \*(L"\s-1TRUSTED CERTIFICATE\*(R"\s0 objects. -This function should not be called on untrusted input. +\&\fId2i_TYPE_fp()\fR is similar to \fId2i_TYPE()\fR except it attempts +to parse data from \s-1FILE\s0 pointer \fBfp\fR. .PP -\&\fIi2d_X509()\fR encodes the structure pointed to by \fBx\fR into \s-1DER\s0 format. -If \fBout\fR is not \fB\s-1NULL\s0\fR is writes the \s-1DER\s0 encoded data to the buffer -at \fB*out\fR, and increments it to point after the data just written. +\&\fIi2d_TYPE()\fR encodes the structure pointed to by \fBa\fR into \s-1DER\s0 format. +If \fBppout\fR is not \fB\s-1NULL\s0\fR, it writes the \s-1DER\s0 encoded data to the buffer +at \fB*ppout\fR, and increments it to point after the data just written. If the return value is negative an error occurred, otherwise it returns the length of the encoded data. .PP -For OpenSSL 0.9.7 and later if \fB*out\fR is \fB\s-1NULL\s0\fR memory will be -allocated for a buffer and the encoded data written to it. In this -case \fB*out\fR is not incremented and it points to the start of the -data just written. -.PP -\&\fIi2d_X509_AUX()\fR is similar to \fIi2d_X509()\fR, but the encoded output contains both -the certificate and any auxiliary trust information. -This is used by the \s-1PEM\s0 routines to write \*(L"\s-1TRUSTED CERTIFICATE\*(R"\s0 objects. -Note, this is a non-standard OpenSSL-specific data format. -.PP -\&\fId2i_X509_bio()\fR is similar to \fId2i_X509()\fR except it attempts -to parse data from \s-1BIO\s0 \fBbp\fR. -.PP -\&\fId2i_X509_fp()\fR is similar to \fId2i_X509()\fR except it attempts -to parse data from \s-1FILE\s0 pointer \fBfp\fR. +If \fB*ppout\fR is \fB\s-1NULL\s0\fR memory will be allocated for a buffer and the encoded +data written to it. In this case \fB*ppout\fR is not incremented and it points +to the start of the data just written. .PP -\&\fIi2d_X509_bio()\fR is similar to \fIi2d_X509()\fR except it writes -the encoding of the structure \fBx\fR to \s-1BIO\s0 \fBbp\fR and it +\&\fIi2d_TYPE_bio()\fR is similar to \fIi2d_TYPE()\fR except it writes +the encoding of the structure \fBa\fR to \s-1BIO\s0 \fBbp\fR and it returns 1 for success and 0 for failure. .PP -\&\fIi2d_X509_fp()\fR is similar to \fIi2d_X509()\fR except it writes -the encoding of the structure \fBx\fR to \s-1BIO\s0 \fBbp\fR and it +\&\fIi2d_TYPE_fp()\fR is similar to \fIi2d_TYPE()\fR except it writes +the encoding of the structure \fBa\fR to \s-1BIO\s0 \fBbp\fR and it returns 1 for success and 0 for failure. .PP -\&\fIi2d_re_X509_tbs()\fR is similar to \fIi2d_X509()\fR except it encodes -only the TBSCertificate portion of the certificate. +These routines do not encrypt private keys and therefore offer no +security; use \fIPEM_write_PrivateKey\fR\|(3) or similar for writing to files. .SH "NOTES" .IX Header "NOTES" -The letters \fBi\fR and \fBd\fR in for example \fBi2d_X509\fR stand for -\&\*(L"internal\*(R" (that is an internal C structure) and \*(L"\s-1DER\*(R".\s0 So -\&\fBi2d_X509\fR converts from internal to \s-1DER.\s0 The \*(L"re\*(R" in -\&\fBi2d_re_X509_tbs\fR stands for \*(L"re-encode\*(R", and ensures that a fresh -encoding is generated in case the object has been modified after -creation (see the \s-1BUGS\s0 section). +The letters \fBi\fR and \fBd\fR in \fBi2d_TYPE\fR stand for +\&\*(L"internal\*(R" (that is, an internal C structure) and \*(L"\s-1DER\*(R"\s0 respectively. +So \fBi2d_TYPE\fR converts from internal to \s-1DER.\s0 .PP The functions can also understand \fB\s-1BER\s0\fR forms. .PP -The actual X509 structure passed to \fIi2d_X509()\fR must be a valid -populated \fBX509\fR structure it can \fBnot\fR simply be fed with an -empty structure such as that returned by \fIX509_new()\fR. +The actual \s-1TYPE\s0 structure passed to \fIi2d_TYPE()\fR must be a valid +populated \fB\s-1TYPE\s0\fR structure \*(-- it \fBcannot\fR simply be fed with an +empty structure such as that returned by \fITYPE_new()\fR. .PP The encoded data is in binary form and may contain embedded zeroes. Therefore any \s-1FILE\s0 pointers or BIOs should be opened in binary mode. -Functions such as \fB\f(BIstrlen()\fB\fR will \fBnot\fR return the correct length +Functions such as \fIstrlen()\fR will \fBnot\fR return the correct length of the encoded structure. .PP -The ways that \fB*in\fR and \fB*out\fR are incremented after the operation +The ways that \fB*ppin\fR and \fB*ppout\fR are incremented after the operation can trap the unwary. See the \fB\s-1WARNINGS\s0\fR section for some common errors. -.PP -The reason for the auto increment behaviour is to reflect a typical +The reason for this-auto increment behaviour is to reflect a typical usage of \s-1ASN1\s0 functions: after one structure is encoded or decoded -another will processed after it. +another will be processed after it. +.PP +The following points about the data types might be useful: +.IP "\fB\s-1ASN1_OBJECT\s0\fR" 4 +.IX Item "ASN1_OBJECT" +Represents an \s-1ASN1 OBJECT IDENTIFIER.\s0 +.IP "\fBDHparams\fR" 4 +.IX Item "DHparams" +Represents a PKCS#3 \s-1DH\s0 parameters structure. +.IP "\fBDHparamx\fR" 4 +.IX Item "DHparamx" +Represents an \s-1ANSI X9.42 DH\s0 parameters structure. +.IP "\fB\s-1DSA_PUBKEY\s0\fR" 4 +.IX Item "DSA_PUBKEY" +Represents a \s-1DSA\s0 public key using a \fBSubjectPublicKeyInfo\fR structure. +.IP "\fBDSAPublicKey, DSAPrivateKey\fR" 4 +.IX Item "DSAPublicKey, DSAPrivateKey" +Use a non-standard OpenSSL format and should be avoided; use \fB\s-1DSA_PUBKEY\s0\fR, +\&\fB\f(BIPEM_write_PrivateKey\fB\|(3)\fR, or similar instead. +.IP "\fBRSAPublicKey\fR" 4 +.IX Item "RSAPublicKey" +Represents a PKCS#1 \s-1RSA\s0 public key structure. +.IP "\fBX509_ALGOR\fR" 4 +.IX Item "X509_ALGOR" +Represents an \fBAlgorithmIdentifier\fR structure as used in \s-1IETF RFC 6960\s0 and +elsewhere. +.IP "\fBX509_Name\fR" 4 +.IX Item "X509_Name" +Represents a \fBName\fR type as used for subject and issuer names in +\&\s-1IETF RFC 6960\s0 and elsewhere. +.IP "\fBX509_REQ\fR" 4 +.IX Item "X509_REQ" +Represents a PKCS#10 certificate request. +.IP "\fBX509_SIG\fR" 4 +.IX Item "X509_SIG" +Represents the \fBDigestInfo\fR structure defined in PKCS#1 and PKCS#7. .SH "EXAMPLES" .IX Header "EXAMPLES" Allocate and encode the \s-1DER\s0 encoding of an X509 structure: .PP .Vb 2 \& int len; -\& unsigned char *buf, *p; -\& -\& len = i2d_X509(x, NULL); -\& -\& buf = OPENSSL_malloc(len); -\& -\& if (buf == NULL) -\& /* error */ -\& -\& p = buf; -\& -\& i2d_X509(x, &p); -.Ve -.PP -If you are using OpenSSL 0.9.7 or later then this can be -simplified to: -.PP -.Vb 2 -\& int len; \& unsigned char *buf; \& \& buf = NULL; -\& \& len = i2d_X509(x, &buf); -\& \& if (len < 0) -\& /* error */ +\& /* error */ .Ve .PP Attempt to decode a buffer: .PP -.Vb 1 +.Vb 3 \& X509 *x; -\& \& unsigned char *buf, *p; -\& \& int len; \& -\& /* Something to setup buf and len */ -\& +\& /* Set up buf and len to point to the input buffer. */ \& p = buf; -\& \& x = d2i_X509(NULL, &p, len); -\& \& if (x == NULL) -\& /* Some error */ +\& /* error */ .Ve .PP Alternative technique: .PP -.Vb 1 +.Vb 3 \& X509 *x; -\& \& unsigned char *buf, *p; -\& \& int len; \& -\& /* Something to setup buf and len */ -\& +\& /* Set up buf and len to point to the input buffer. */ \& p = buf; -\& \& x = NULL; \& -\& if(!d2i_X509(&x, &p, len)) -\& /* Some error */ +\& if (d2i_X509(&x, &p, len) == NULL) +\& /* error */ .Ve .SH "WARNINGS" .IX Header "WARNINGS" -The use of temporary variable is mandatory. A common +Using a temporary variable is mandatory. A common mistake is to attempt to use a buffer directly as follows: .PP .Vb 2 @@ -318,89 +307,68 @@ mistake is to attempt to use a buffer directly as follows: \& unsigned char *buf; \& \& len = i2d_X509(x, NULL); -\& \& buf = OPENSSL_malloc(len); -\& -\& if (buf == NULL) -\& /* error */ -\& +\& ... \& i2d_X509(x, &buf); -\& -\& /* Other stuff ... */ -\& +\& ... \& OPENSSL_free(buf); .Ve .PP This code will result in \fBbuf\fR apparently containing garbage because it was incremented after the call to point after the data just written. -Also \fBbuf\fR will no longer contain the pointer allocated by \fB\f(BIOPENSSL_malloc()\fB\fR -and the subsequent call to \fB\f(BIOPENSSL_free()\fB\fR may well crash. -.PP -The auto allocation feature (setting buf to \s-1NULL\s0) only works on OpenSSL -0.9.7 and later. Attempts to use it on earlier versions will typically -cause a segmentation violation. +Also \fBbuf\fR will no longer contain the pointer allocated by \fIOPENSSL_malloc()\fR +and the subsequent call to \fIOPENSSL_free()\fR is likely to crash. .PP -Another trap to avoid is misuse of the \fBxp\fR argument to \fB\f(BId2i_X509()\fB\fR: +Another trap to avoid is misuse of the \fBa\fR argument to \fId2i_TYPE()\fR: .PP .Vb 1 \& X509 *x; \& -\& if (!d2i_X509(&x, &p, len)) -\& /* Some error */ +\& if (d2i_X509(&x, &p, len) == NULL) +\& /* error */ .Ve .PP -This will probably crash somewhere in \fB\f(BId2i_X509()\fB\fR. The reason for this +This will probably crash somewhere in \fId2i_X509()\fR. The reason for this is that the variable \fBx\fR is uninitialized and an attempt will be made to interpret its (invalid) value as an \fBX509\fR structure, typically causing a segmentation violation. If \fBx\fR is set to \s-1NULL\s0 first then this will not happen. .SH "BUGS" .IX Header "BUGS" -In some versions of OpenSSL the \*(L"reuse\*(R" behaviour of \fId2i_X509()\fR when +In some versions of OpenSSL the \*(L"reuse\*(R" behaviour of \fId2i_TYPE()\fR when \&\fB*px\fR is valid is broken and some parts of the reused structure may persist if they are not present in the new one. As a result the use of this \*(L"reuse\*(R" behaviour is strongly discouraged. .PP -\&\fIi2d_X509()\fR will not return an error in many versions of OpenSSL, +\&\fIi2d_TYPE()\fR will not return an error in many versions of OpenSSL, if mandatory fields are not initialized due to a programming error then the encoded structure may contain invalid data or omit the -fields entirely and will not be parsed by \fId2i_X509()\fR. This may be -fixed in future so code should not assume that \fIi2d_X509()\fR will +fields entirely and will not be parsed by \fId2i_TYPE()\fR. This may be +fixed in future so code should not assume that \fIi2d_TYPE()\fR will always succeed. .PP -The encoding of the TBSCertificate portion of a certificate is cached -in the \fBX509\fR structure internally to improve encoding performance -and to ensure certificate signatures are verified correctly in some -certificates with broken (non-DER) encodings. -.PP -Any function which encodes an X509 structure such as \fIi2d_X509()\fR, -\&\fIi2d_X509_fp()\fR or \fIi2d_X509_bio()\fR may return a stale encoding if the -\&\fBX509\fR structure has been modified after deserialization or previous -serialization. -.PP -If, after modification, the \fBX509\fR object is re-signed with \fIX509_sign()\fR, -the encoding is automatically renewed. Otherwise, the encoding of the -TBSCertificate portion of the \fBX509\fR can be manually renewed by calling -\&\fIi2d_re_X509_tbs()\fR. +Any function which encodes a structure (\fIi2d_TYPE()\fR, +\&\fIi2d_TYPE()\fR or \fIi2d_TYPE()\fR) may return a stale encoding if the +structure has been modified after deserialization or previous +serialization. This is because some objects cache the encoding for +efficiency reasons. .SH "RETURN VALUES" .IX Header "RETURN VALUES" -\&\fId2i_X509()\fR, \fId2i_X509_bio()\fR and \fId2i_X509_fp()\fR return a valid \fBX509\fR structure -or \fB\s-1NULL\s0\fR if an error occurs. The error code that can be obtained by -\&\fIERR_get_error\fR\|(3). If the \*(L"reuse\*(R" capability has been used -with a valid X509 structure being passed in via \fBpx\fR then the object is not -freed in the event of error but may be in a potentially invalid or inconsistent -state. -.PP -\&\fIi2d_X509()\fR returns the number of bytes successfully encoded or a negative -value if an error occurs. The error code can be obtained by -\&\fIERR_get_error\fR\|(3). -.PP -\&\fIi2d_X509_bio()\fR and \fIi2d_X509_fp()\fR return 1 for success and 0 if an error -occurs The error code can be obtained by \fIERR_get_error\fR\|(3). -.SH "SEE ALSO" -.IX Header "SEE ALSO" -\&\fIERR_get_error\fR\|(3) -.SH "HISTORY" -.IX Header "HISTORY" -d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio and i2d_X509_fp -are available in all versions of SSLeay and OpenSSL. +\&\fId2i_TYPE()\fR, \fId2i_TYPE_bio()\fR and \fId2i_TYPE_fp()\fR return a valid \fB\s-1TYPE\s0\fR structure +or \fB\s-1NULL\s0\fR if an error occurs. If the \*(L"reuse\*(R" capability has been used with +a valid structure being passed in via \fBa\fR, then the object is not freed in +the event of error but may be in a potentially invalid or inconsistent state. +.PP +\&\fIi2d_TYPE()\fR returns the number of bytes successfully encoded or a negative +value if an error occurs. +.PP +\&\fIi2d_TYPE_bio()\fR and \fIi2d_TYPE_fp()\fR return 1 for success and 0 if an error +occurs. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 1998\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +<https://www.openssl.org/source/license.html>. |