Class CpPemEncoding

Provides methods for reading and writing the IETF RFC 7468 subset of PEM (Privacy-Enhanced Mail) textual encodings. This class cannot be inherited.

Inheritance

object

CpPemEncoding

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: CryptoPro.Security.Cryptography

Assembly: CryptoPro.Security.Cryptography.dll

Syntax

public static class CpPemEncoding

Methods

Find(ReadOnlySpan<char>)

Finds the first PEM-encoded data.

Declaration

public static CpPemFields Find(ReadOnlySpan<char> pemData)

Parameters

Type	Name	Description
ReadOnlySpan<char>	pemData	The text containing the PEM-encoded data.

Returns

Type	Description
CpPemFields	A value that specifies the location, label, and data location of the encoded data.

Remarks

IETF RFC 7468 permits different decoding rules. This method always uses lax rules.

Exceptions

Type	Condition
ArgumentException	pemData does not contain a well-formed PEM-encoded value.

FindUtf8(ReadOnlySpan<byte>)

Finds the first PEM-encoded data.

Declaration

public static CpPemFields FindUtf8(ReadOnlySpan<byte> pemData)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	pemData	The text containing the PEM-encoded data.

Returns

Type	Description
CpPemFields	A value that specifies the location, label, and data location of the encoded data.

Remarks

IETF RFC 7468 permits different decoding rules. This method always uses lax rules.

This does not validate the UTF-8 data outside of encapsulation boundaries and is ignored. It is the caller's responsibility to ensure the entire input is UTF-8 if required.

Exceptions

Type	Condition
ArgumentException	pemData does not contain a well-formed PEM-encoded value.

GetEncodedSize(int, int)

Determines the length of a PEM-encoded value, in characters, given the length of a label and binary data.

Declaration

public static int GetEncodedSize(int labelLength, int dataLength)

Parameters

Type	Name	Description
int	labelLength	The length of the label, in characters.
int	dataLength	The length of the data, in bytes.

Returns

Type	Description
int	The number of characters in the encoded PEM.

Exceptions

Type	Condition
ArgumentOutOfRangeException	labelLength is a negative value. -or- dataLength is a negative value. -or- labelLength exceeds the maximum possible label length. -or- dataLength exceeds the maximum possible encoded data length.
ArgumentException	The length of the PEM-encoded value is larger than MaxValue.

TryFind(ReadOnlySpan<char>, out CpPemFields)

Attempts to find the first PEM-encoded data.

Declaration

public static bool TryFind(ReadOnlySpan<char> pemData, out CpPemFields fields)

Parameters

Type	Name	Description
ReadOnlySpan<char>	pemData	The text containing the PEM-encoded data.
CpPemFields	fields	When this method returns, contains a value that specifies the location, label, and data location of the encoded data; or that specifies those locations as empty if no PEM-encoded data is found. This parameter is treated as uninitialized.

Returns

Type	Description
bool	true if PEM-encoded data was found; otherwise false.

Remarks

IETF RFC 7468 permits different decoding rules. This method always uses lax rules.

TryFindUtf8(ReadOnlySpan<byte>, out CpPemFields)

Attempts to find the first PEM-encoded data.

Declaration

public static bool TryFindUtf8(ReadOnlySpan<byte> pemData, out CpPemFields fields)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	pemData	The text containing the PEM-encoded data.
CpPemFields	fields	When this method returns, contains a value that specifies the location, label, and data location of the encoded data; or that specifies those locations as empty if no PEM-encoded data is found. This parameter is treated as uninitialized.

Returns

Type	Description
bool	true if PEM-encoded data was found; otherwise false.

Remarks

IETF RFC 7468 permits different decoding rules. This method always uses lax rules.

This does not validate the UTF-8 data outside of encapsulation boundaries and is ignored. It is the caller's responsibility to ensure the entire input is UTF-8 if required.

TryWrite(ReadOnlySpan<char>, ReadOnlySpan<byte>, Span<char>, out int)

Tries to write the provided data and label as PEM-encoded data into a provided buffer.

Declaration

public static bool TryWrite(ReadOnlySpan<char> label, ReadOnlySpan<byte> data, Span<char> destination, out int charsWritten)

Parameters

Type	Name	Description
ReadOnlySpan<char>	label	The label to write.
ReadOnlySpan<byte>	data	The data to write.
Span<char>	destination	The buffer to receive the PEM-encoded text.
int	charsWritten	When this method returns, this parameter contains the number of characters written to destination. This parameter is treated as uninitialized.

Returns

Type	Description
bool	true if destination is large enough to contain the PEM-encoded text, otherwise false.

Remarks

This method always wraps the base-64 encoded text to 64 characters, per the recommended wrapping of IETF RFC 7468. Unix-style line endings are used for line breaks.

Exceptions

Type	Condition
ArgumentOutOfRangeException	label exceeds the maximum possible label length. -or- data exceeds the maximum possible encoded data length.
ArgumentException	The resulting PEM-encoded text is larger than MaxValue. - or - label contains invalid characters.

TryWriteUtf8(ReadOnlySpan<byte>, ReadOnlySpan<byte>, Span<byte>, out int)

Tries to write the provided data and label as PEM-encoded data into a provided buffer.

Declaration

public static bool TryWriteUtf8(ReadOnlySpan<byte> utf8Label, ReadOnlySpan<byte> data, Span<byte> destination, out int bytesWritten)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	utf8Label	The label to write.
ReadOnlySpan<byte>	data	The data to write.
Span<byte>	destination	The buffer to receive the PEM-encoded text.
int	bytesWritten	When this method returns, this parameter contains the number of UTF-8 encoded bytes written to destination.

Returns

Type	Description
bool	true if destination is large enough to contain the PEM-encoded text, otherwise false.

Remarks

This method always wraps the base-64 encoded text to 64 characters, per the recommended wrapping of IETF RFC 7468. Unix-style line endings are used for line breaks.

Exceptions

Type	Condition
ArgumentOutOfRangeException	utf8Label exceeds the maximum possible label length. -or- data exceeds the maximum possible encoded data length.
ArgumentException	The resulting PEM-encoded text is larger than MaxValue. - or - utf8Label contains invalid characters or is malformed UTF-8.

Write(ReadOnlySpan<char>, ReadOnlySpan<byte>)

Creates an encoded PEM with the given label and data.

Declaration

public static char[] Write(ReadOnlySpan<char> label, ReadOnlySpan<byte> data)

Parameters

Type	Name	Description
ReadOnlySpan<char>	label	The label to encode.
ReadOnlySpan<byte>	data	The data to encode.

Returns

Type	Description
char[]	A character array of the encoded PEM.

Remarks

This method always wraps the base-64 encoded text to 64 characters, per the recommended wrapping of RFC-7468. Unix-style line endings are used for line breaks.

Exceptions

Type	Condition
ArgumentOutOfRangeException	label exceeds the maximum possible label length. -or- data exceeds the maximum possible encoded data length.
ArgumentException	The resulting PEM-encoded text is larger than MaxValue. - or - label contains invalid characters.

WriteString(ReadOnlySpan<char>, ReadOnlySpan<byte>)

Creates an encoded PEM with the given label and data.

Declaration

public static string WriteString(ReadOnlySpan<char> label, ReadOnlySpan<byte> data)

Parameters

Type	Name	Description
ReadOnlySpan<char>	label	The label to encode.
ReadOnlySpan<byte>	data	The data to encode.

Returns

Type	Description
string	A string of the encoded PEM.

Remarks

This method always wraps the base-64 encoded text to 64 characters, per the recommended wrapping of RFC-7468. Unix-style line endings are used for line breaks.

Exceptions

Type	Condition
ArgumentOutOfRangeException	label exceeds the maximum possible label length. -or- data exceeds the maximum possible encoded data length.
ArgumentException	The resulting PEM-encoded text is larger than MaxValue. or - label contains invalid characters.

WriteUtf8(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Creates an encoded PEM with the given label and data.

Declaration

public static byte[] WriteUtf8(ReadOnlySpan<byte> utf8Label, ReadOnlySpan<byte> data)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	utf8Label	The label to encode.
ReadOnlySpan<byte>	data	The data to encode.

Returns

Type	Description
byte[]	An array containing the bytes representing the UTF-8 encoding of the PEM.

Remarks

This method always wraps the base-64 encoded text to 64 characters, per the recommended wrapping of RFC-7468. Unix-style line endings are used for line breaks.

Exceptions

Type	Condition
ArgumentOutOfRangeException	utf8Label exceeds the maximum possible label length. -or- data exceeds the maximum possible encoded data length.
ArgumentException	The resulting PEM-encoded text is larger than MaxValue. -or- utf8Label contains invalid characters or is malformed UTF-8.