doc: crypto.sign and crypto.verify string/buffer keys must be pem

📗 API Reference Docs Problem

Version: v12.16.2

Platform: Darwin Jacobs-MacBook-Pro.local 18.6.0 Darwin Kernel Version 18.6.0: Thu Apr 25 23:16:27 PDT 2019; root:xnu-4903.261.4~2/RELEASE_X86_64 x86_64

Subsystem: crypto

Location

Section of the site where the content exists

Affected URL(s):

https://nodejs.org/api/crypto.html#crypto_crypto_sign_algorithm_data_key
https://nodejs.org/api/crypto.html#crypto_crypto_verify_algorithm_data_key_signature
possibly (probably?) others

Description

Concise explanation of the problem

According to the documentation for crypto.sign and crypto.verify, the key argument may be a string, buffer, object, or KeyObject. It does not mention that if the key is a string or buffer, it must be pem format. Passing a key with der format will result in an error error:0909006C:PEM routines:get_name:no start line

The source code is quite clear that keys are assumed to be pem.

node/lib/internal/crypto/keys.js

Lines 277 to 280 in d6fe46f

    
           } else if (typeof key === 'string' || isArrayBufferView(key)) { 
        
             // Expect PEM by default, mostly for backward compatibility. 
        
             return { format: kKeyFormatPEM, data: key }; 
        
           } else if (typeof key === 'object') {

I would like to work on this issue and
submit a pull request.

The docs do note

If key is not a KeyObject, this function behaves as if key had been passed to crypto.createPrivateKey().

If key is not a KeyObject, this function behaves as if key had been passed to crypto.createPublicKey().

Then the create*Key methods do say that

If key is a string or Buffer, format is assumed to be 'pem'

Personally i think this is clear and removes a lot of documentation duplication that would have to be in place if this was to be mentioned all repeated in crypto.sign, crypto.verify, Sign.prototype.sign, and Verify.prototype.verify

I agree with the avoiding-duplication point. Still, if this is tripping up users, then I also wouldn't mind mentioning PEM. Maybe something like this?

If key is not a KeyObject, this function behaves as if key had been passed to crypto.createPublicKey(). For example, strings and buffers must be in PEM format.

This issue has been marked as stale due to 210 days of inactivity.
It will be automatically closed in 30 days if no further activity occurs. If this is still relevant, please leave a comment or update it to keep it open.

doc: clarify PEM format for signing keys

Navigation Menu

Repository navigation

doc: crypto.sign and crypto.verify string/buffer keys must be pem #35331

📗 API Reference Docs Problem

Location

Description

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	} else if (typeof key === 'string' \|\| isArrayBufferView(key)) {
	// Expect PEM by default, mostly for backward compatibility.
	return { format: kKeyFormatPEM, data: key };
	} else if (typeof key === 'object') {

doc: crypto.sign and crypto.verify string/buffer keys must be pem #35331

Description

📗 API Reference Docs Problem

Location

Description

Activity

panva commented on Nov 30, 2020

Trott commented on Dec 2, 2020

github-actions commented on Jun 27, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions