.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "OSSL_SERIALIZER_CTX_NEW_BY_EVP_PKEY 3SSL" .TH OSSL_SERIALIZER_CTX_NEW_BY_EVP_PKEY 3SSL "2020-07-06" "3.0.0-alpha4" "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" OSSL_SERIALIZER_CTX_new_by_EVP_PKEY, OSSL_SERIALIZER_CTX_set_cipher, OSSL_SERIALIZER_CTX_set_passphrase, OSSL_SERIALIZER_CTX_set_passphrase_cb, OSSL_SERIALIZER_CTX_set_passphrase_ui, OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ, OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ, OSSL_SERIALIZER_Parameters_TO_PEM_PQ, OSSL_SERIALIZER_PUBKEY_TO_DER_PQ, OSSL_SERIALIZER_PrivateKey_TO_DER_PQ, OSSL_SERIALIZER_Parameters_TO_DER_PQ, OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ, OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ, OSSL_SERIALIZER_Parameters_TO_TEXT_PQ \&\- Serializer routines to serialize EVP_PKEYs .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& OSSL_SERIALIZER_CTX *OSSL_SERIALIZER_CTX_new_by_EVP_PKEY(const EVP_PKEY *pkey, \& const char *propquery); \& \& int OSSL_SERIALIZER_CTX_set_cipher(OSSL_SERIALIZER_CTX *ctx, \& const char *cipher_name, \& const char *propquery); \& int OSSL_SERIALIZER_CTX_set_passphrase(OSSL_SERIALIZER_CTX *ctx, \& const unsigned char *kstr, \& size_t klen); \& int OSSL_SERIALIZER_CTX_set_passphrase_cb(OSSL_SERIALIZER_CTX *ctx, int enc, \& pem_password_cb *cb, void *cbarg); \& int OSSL_SERIALIZER_CTX_set_passphrase_ui(OSSL_SERIALIZER_CTX *ctx, \& const UI_METHOD *ui_method, \& void *ui_data); \& \& #define OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ "format=pem,type=public" \& #define OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ "format=pem,type=private" \& #define OSSL_SERIALIZER_Parameters_TO_PEM_PQ "format=pem,type=parameters" \& \& #define OSSL_SERIALIZER_PUBKEY_TO_DER_PQ "format=der,type=public" \& #define OSSL_SERIALIZER_PrivateKey_TO_DER_PQ "format=der,type=private" \& #define OSSL_SERIALIZER_Parameters_TO_DER_PQ "format=der,type=parameters" \& \& #define OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ "format=text,type=public" \& #define OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ "format=text,type=private" \& #define OSSL_SERIALIZER_Parameters_TO_TEXT_PQ "format=text,type=parameters" .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBOSSL_SERIALIZER_CTX_new_by_EVP_PKEY()\fR creates a \fB\s-1OSSL_SERIALIZER_CTX\s0\fR with a suitable attached output routine for \fB\s-1EVP_PKEY\s0\fRs. It will search for a serializer implementation that matches the algorithm of the \fB\s-1EVP_PKEY\s0\fR and the property query given with \fIpropquery\fR. It will prefer to find a serializer from the same provider as the key data of the \fB\s-1EVP_PKEY\s0\fR itself, but failing that, it will choose the first serializer that supplies a generic serializing function. .PP If no suitable serializer was found, \fBOSSL_SERIALIZER_CTX_new_by_EVP_PKEY()\fR still creates a \fB\s-1OSSL_SERIALIZER_CTX\s0\fR, but with no associated serializer (\fBOSSL_SERIALIZER_CTX_get_serializer\fR\|(3) returns \s-1NULL\s0). This helps the caller distinguish between an error when creating the \fB\s-1OSSL_SERIALIZER_CTX\s0\fR, and the lack the serializer support and act accordingly. .PP \&\fBOSSL_SERIALIZER_CTX_set_cipher()\fR tells the implementation what cipher should be used to encrypt serialized keys. The cipher is given by name \fIcipher_name\fR. The interpretation of that \fIcipher_name\fR is implementation dependent. The implementation may implement the digest directly itself or by other implementations, or it may choose to fetch it. If the implementation supports fetching the cipher, then it may use \fIpropquery\fR as properties to be queried for when fetching. \&\fIcipher_name\fR may also be \s-1NULL,\s0 which will result in unencrypted serialization. .PP \&\fBOSSL_SERIALIZER_CTX_set_passphrase()\fR gives the implementation a pass phrase to use when encrypting the serialized private key. Alternatively, a pass phrase callback may be specified with the following functions. .PP \&\fBOSSL_SERIALIZER_CTX_set_passphrase_cb()\fR and \&\fBOSSL_SERIALIZER_CTX_set_passphrase_ui()\fR sets up a callback method that the implementation can use to prompt for a pass phrase. .PP The macros \fB\s-1OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ\s0\fR, \&\fBOSSL_SERIALIZER_PrivateKey_TO_PEM_PQ\fR, \&\fBOSSL_SERIALIZER_Parameters_TO_PEM_PQ\fR, \&\fB\s-1OSSL_SERIALIZER_PUBKEY_TO_DER_PQ\s0\fR, \&\fBOSSL_SERIALIZER_PrivateKey_TO_DER_PQ\fR, \&\fBOSSL_SERIALIZER_Parameters_TO_DER_PQ\fR, \&\fB\s-1OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ\s0\fR, \&\fBOSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ\fR, \&\fBOSSL_SERIALIZER_Parameters_TO_TEXT_PQ\fR are convenience macros with property queries to serialize the \fB\s-1EVP_PKEY\s0\fR as a public key, private key or parameters to \fB\s-1PEM\s0\fR, to \fB\s-1DER\s0\fR, or to text. .SH "RETURN VALUES" .IX Header "RETURN VALUES" \&\fBOSSL_SERIALIZER_CTX_new_by_EVP_PKEY()\fR returns a pointer to a \&\fB\s-1OSSL_SERIALIZER_CTX\s0\fR, or \s-1NULL\s0 if it couldn't be created. .PP \&\fBOSSL_SERIALIZER_CTX_set_cipher()\fR, \&\fBOSSL_SERIALIZER_CTX_set_passphrase()\fR, \&\fBOSSL_SERIALIZER_CTX_set_passphrase_cb()\fR, and \&\fBOSSL_SERIALIZER_CTX_set_passphrase_ui()\fR all return 1 on success, or 0 on failure. .SH "NOTES" .IX Header "NOTES" Parts of the function and macro names are made to match already existing OpenSSL names. .PP \&\fB\s-1EVP_PKEY\s0\fR in \fBOSSL_SERIALIZER_CTX_new_by_EVP_PKEY()\fR matches the type name, thus making for the naming pattern \&\fBOSSL_SERIALIZER_CTX_new_by_\f(BI\s-1TYPE\s0\fB\fR() when new types are handled. .PP \&\fB\s-1PUBKEY\s0\fR, \fBPrivateKey\fR and \fBParameters\fR in the macro names match the \fB\f(BI\s-1TYPE\s0\fB\fR part of of \fBPEM_write_bio_\f(BI\s-1TYPE\s0\fB\fR functions as well as \fBi2d_\f(BI\s-1TYPE\s0\fB_bio\fR functions. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBprovider\fR\|(7), \s-1\fBOSSL_SERIALIZER\s0\fR\|(3), \s-1\fBOSSL_SERIALIZER_CTX\s0\fR\|(3) .SH "HISTORY" .IX Header "HISTORY" The functions described here were added in OpenSSL 3.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2019\-2020 The OpenSSL Project Authors. All Rights Reserved. .PP Licensed under the Apache License 2.0 (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 .