diff options
Diffstat (limited to 'src/include/openssl/pkcs8.h')
| -rw-r--r-- | src/include/openssl/pkcs8.h | 144 |
1 files changed, 72 insertions, 72 deletions
diff --git a/src/include/openssl/pkcs8.h b/src/include/openssl/pkcs8.h index d30ea8e3..f865c767 100644 --- a/src/include/openssl/pkcs8.h +++ b/src/include/openssl/pkcs8.h @@ -66,121 +66,121 @@ extern "C" { #endif -/* PKCS8_encrypt serializes and encrypts a PKCS8_PRIV_KEY_INFO with PBES1 or - * PBES2 as defined in PKCS #5. Only pbeWithSHAAnd128BitRC4, - * pbeWithSHAAnd3-KeyTripleDES-CBC and pbeWithSHA1And40BitRC2, defined in PKCS - * #12, and PBES2, are supported. PBES2 is selected by setting |cipher| and - * passing -1 for |pbe_nid|. Otherwise, PBES1 is used and |cipher| is ignored. - * - * |pass| is used as the password. If a PBES1 scheme from PKCS #12 is used, this - * will be converted to a raw byte string as specified in B.1 of PKCS #12. If - * |pass| is NULL, it will be encoded as the empty byte string rather than two - * zero bytes, the PKCS #12 encoding of the empty string. - * - * If |salt| is NULL, a random salt of |salt_len| bytes is generated. If - * |salt_len| is zero, a default salt length is used instead. - * - * The resulting structure is stored in an |X509_SIG| which must be freed by the - * caller. */ +// PKCS8_encrypt serializes and encrypts a PKCS8_PRIV_KEY_INFO with PBES1 or +// PBES2 as defined in PKCS #5. Only pbeWithSHAAnd128BitRC4, +// pbeWithSHAAnd3-KeyTripleDES-CBC and pbeWithSHA1And40BitRC2, defined in PKCS +// #12, and PBES2, are supported. PBES2 is selected by setting |cipher| and +// passing -1 for |pbe_nid|. Otherwise, PBES1 is used and |cipher| is ignored. +// +// |pass| is used as the password. If a PBES1 scheme from PKCS #12 is used, this +// will be converted to a raw byte string as specified in B.1 of PKCS #12. If +// |pass| is NULL, it will be encoded as the empty byte string rather than two +// zero bytes, the PKCS #12 encoding of the empty string. +// +// If |salt| is NULL, a random salt of |salt_len| bytes is generated. If +// |salt_len| is zero, a default salt length is used instead. +// +// The resulting structure is stored in an |X509_SIG| which must be freed by the +// caller. OPENSSL_EXPORT X509_SIG *PKCS8_encrypt(int pbe_nid, const EVP_CIPHER *cipher, const char *pass, int pass_len, const uint8_t *salt, size_t salt_len, int iterations, PKCS8_PRIV_KEY_INFO *p8inf); -/* PKCS8_marshal_encrypted_private_key behaves like |PKCS8_encrypt| but encrypts - * an |EVP_PKEY| and writes the serialized EncryptedPrivateKeyInfo to |out|. It - * returns one on success and zero on error. */ +// PKCS8_marshal_encrypted_private_key behaves like |PKCS8_encrypt| but encrypts +// an |EVP_PKEY| and writes the serialized EncryptedPrivateKeyInfo to |out|. It +// returns one on success and zero on error. OPENSSL_EXPORT int PKCS8_marshal_encrypted_private_key( CBB *out, int pbe_nid, const EVP_CIPHER *cipher, const char *pass, size_t pass_len, const uint8_t *salt, size_t salt_len, int iterations, const EVP_PKEY *pkey); -/* PKCS8_decrypt decrypts and decodes a PKCS8_PRIV_KEY_INFO with PBES1 or PBES2 - * as defined in PKCS #5. Only pbeWithSHAAnd128BitRC4, - * pbeWithSHAAnd3-KeyTripleDES-CBC and pbeWithSHA1And40BitRC2, and PBES2, - * defined in PKCS #12, are supported. - * - * |pass| is used as the password. If a PBES1 scheme from PKCS #12 is used, this - * will be converted to a raw byte string as specified in B.1 of PKCS #12. If - * |pass| is NULL, it will be encoded as the empty byte string rather than two - * zero bytes, the PKCS #12 encoding of the empty string. - * - * The resulting structure must be freed by the caller. */ +// PKCS8_decrypt decrypts and decodes a PKCS8_PRIV_KEY_INFO with PBES1 or PBES2 +// as defined in PKCS #5. Only pbeWithSHAAnd128BitRC4, +// pbeWithSHAAnd3-KeyTripleDES-CBC and pbeWithSHA1And40BitRC2, and PBES2, +// defined in PKCS #12, are supported. +// +// |pass| is used as the password. If a PBES1 scheme from PKCS #12 is used, this +// will be converted to a raw byte string as specified in B.1 of PKCS #12. If +// |pass| is NULL, it will be encoded as the empty byte string rather than two +// zero bytes, the PKCS #12 encoding of the empty string. +// +// The resulting structure must be freed by the caller. OPENSSL_EXPORT PKCS8_PRIV_KEY_INFO *PKCS8_decrypt(X509_SIG *pkcs8, const char *pass, int pass_len); -/* PKCS8_parse_encrypted_private_key behaves like |PKCS8_decrypt| but it parses - * the EncryptedPrivateKeyInfo structure from |cbs| and advances |cbs|. It - * returns a newly-allocated |EVP_PKEY| on success and zero on error. */ +// PKCS8_parse_encrypted_private_key behaves like |PKCS8_decrypt| but it parses +// the EncryptedPrivateKeyInfo structure from |cbs| and advances |cbs|. It +// returns a newly-allocated |EVP_PKEY| on success and zero on error. OPENSSL_EXPORT EVP_PKEY *PKCS8_parse_encrypted_private_key(CBS *cbs, const char *pass, size_t pass_len); -/* PKCS12_get_key_and_certs parses a PKCS#12 structure from |in|, authenticates - * and decrypts it using |password|, sets |*out_key| to the included private - * key and appends the included certificates to |out_certs|. It returns one on - * success and zero on error. The caller takes ownership of the outputs. */ +// PKCS12_get_key_and_certs parses a PKCS#12 structure from |in|, authenticates +// and decrypts it using |password|, sets |*out_key| to the included private +// key and appends the included certificates to |out_certs|. It returns one on +// success and zero on error. The caller takes ownership of the outputs. OPENSSL_EXPORT int PKCS12_get_key_and_certs(EVP_PKEY **out_key, STACK_OF(X509) *out_certs, CBS *in, const char *password); -/* Deprecated functions. */ +// Deprecated functions. -/* PKCS12_PBE_add does nothing. It exists for compatibility with OpenSSL. */ +// PKCS12_PBE_add does nothing. It exists for compatibility with OpenSSL. OPENSSL_EXPORT void PKCS12_PBE_add(void); -/* d2i_PKCS12 is a dummy function that copies |*ber_bytes| into a - * |PKCS12| structure. The |out_p12| argument should be NULL(✝). On exit, - * |*ber_bytes| will be advanced by |ber_len|. It returns a fresh |PKCS12| - * structure or NULL on error. - * - * Note: unlike other d2i functions, |d2i_PKCS12| will always consume |ber_len| - * bytes. - * - * (✝) If |out_p12| is not NULL and the function is successful, |*out_p12| will - * be freed if not NULL itself and the result will be written to |*out_p12|. - * New code should not depend on this. */ +// d2i_PKCS12 is a dummy function that copies |*ber_bytes| into a +// |PKCS12| structure. The |out_p12| argument should be NULL(✝). On exit, +// |*ber_bytes| will be advanced by |ber_len|. It returns a fresh |PKCS12| +// structure or NULL on error. +// +// Note: unlike other d2i functions, |d2i_PKCS12| will always consume |ber_len| +// bytes. +// +// (✝) If |out_p12| is not NULL and the function is successful, |*out_p12| will +// be freed if not NULL itself and the result will be written to |*out_p12|. +// New code should not depend on this. OPENSSL_EXPORT PKCS12 *d2i_PKCS12(PKCS12 **out_p12, const uint8_t **ber_bytes, size_t ber_len); -/* d2i_PKCS12_bio acts like |d2i_PKCS12| but reads from a |BIO|. */ +// d2i_PKCS12_bio acts like |d2i_PKCS12| but reads from a |BIO|. OPENSSL_EXPORT PKCS12* d2i_PKCS12_bio(BIO *bio, PKCS12 **out_p12); -/* d2i_PKCS12_fp acts like |d2i_PKCS12| but reads from a |FILE|. */ +// d2i_PKCS12_fp acts like |d2i_PKCS12| but reads from a |FILE|. OPENSSL_EXPORT PKCS12* d2i_PKCS12_fp(FILE *fp, PKCS12 **out_p12); -/* PKCS12_parse calls |PKCS12_get_key_and_certs| on the ASN.1 data stored in - * |p12|. The |out_pkey| and |out_cert| arguments must not be NULL and, on - * successful exit, the private key and first certificate will be stored in - * them. The |out_ca_certs| argument may be NULL but, if not, then any extra - * certificates will be appended to |*out_ca_certs|. If |*out_ca_certs| is NULL - * then it will be set to a freshly allocated stack containing the extra certs. - * - * It returns one on success and zero on error. */ +// PKCS12_parse calls |PKCS12_get_key_and_certs| on the ASN.1 data stored in +// |p12|. The |out_pkey| and |out_cert| arguments must not be NULL and, on +// successful exit, the private key and first certificate will be stored in +// them. The |out_ca_certs| argument may be NULL but, if not, then any extra +// certificates will be appended to |*out_ca_certs|. If |*out_ca_certs| is NULL +// then it will be set to a freshly allocated stack containing the extra certs. +// +// It returns one on success and zero on error. OPENSSL_EXPORT int PKCS12_parse(const PKCS12 *p12, const char *password, EVP_PKEY **out_pkey, X509 **out_cert, STACK_OF(X509) **out_ca_certs); -/* PKCS12_verify_mac returns one if |password| is a valid password for |p12| - * and zero otherwise. Since |PKCS12_parse| doesn't take a length parameter, - * it's not actually possible to use a non-NUL-terminated password to actually - * get anything from a |PKCS12|. Thus |password| and |password_len| may be - * |NULL| and zero, respectively, or else |password_len| may be -1, or else - * |password[password_len]| must be zero and no other NUL bytes may appear in - * |password|. If the |password_len| checks fail, zero is returned - * immediately. */ +// PKCS12_verify_mac returns one if |password| is a valid password for |p12| +// and zero otherwise. Since |PKCS12_parse| doesn't take a length parameter, +// it's not actually possible to use a non-NUL-terminated password to actually +// get anything from a |PKCS12|. Thus |password| and |password_len| may be +// |NULL| and zero, respectively, or else |password_len| may be -1, or else +// |password[password_len]| must be zero and no other NUL bytes may appear in +// |password|. If the |password_len| checks fail, zero is returned +// immediately. OPENSSL_EXPORT int PKCS12_verify_mac(const PKCS12 *p12, const char *password, int password_len); -/* PKCS12_free frees |p12| and its contents. */ +// PKCS12_free frees |p12| and its contents. OPENSSL_EXPORT void PKCS12_free(PKCS12 *p12); #if defined(__cplusplus) -} /* extern C */ +} // extern C extern "C++" { @@ -191,7 +191,7 @@ BORINGSSL_MAKE_DELETER(PKCS8_PRIV_KEY_INFO, PKCS8_PRIV_KEY_INFO_free) } // namespace bssl -} /* extern C++ */ +} // extern C++ #endif @@ -227,4 +227,4 @@ BORINGSSL_MAKE_DELETER(PKCS8_PRIV_KEY_INFO, PKCS8_PRIV_KEY_INFO_free) #define PKCS8_R_BAD_ITERATION_COUNT 129 #define PKCS8_R_UNSUPPORTED_PRF 130 -#endif /* OPENSSL_HEADER_PKCS8_H */ +#endif // OPENSSL_HEADER_PKCS8_H |