1C:Enterprise 8.3. Developer Guide. Contents
THE CRYPTOGRAPHIC MECHANISM
When 1C:Enterprise is used in automation systems, you might need to check that a document stored in the system wasn't modified (for example, a document with a text of the agreement is attached to the Agreement database object). There also could be a need to transfer some signed information or implement approval of a document within the system. Some scenarios are possible when you need to transfer information via public channels so that it would be impossible to read the information if it is intercepted (data encryption).
For that purpose, 1C:Enterprise implements a cryptographic mechanism based on asymmetric encryption (a couple of keys are used, public and private).
IMPORTANT!
The 1C:Enterprise cryptographic mechanism does not actually implement cryptographic algorithms. It provides a set of objects that can be used to communicate with third parties’ external cryptographic modules.
22.1. GENERAL MECHANISM DESCRIPTION
The public key is used to transfer data via public channels, and the private key is not distributed and should be protected to a maximum degree.
The receiver public keys should be known to encrypt data. A private key coupled with the public key used for encryption is needed to decrypt data. A private key is required to generate a digital signature, and the signer's public key is required to validate the signature (most often, a public key is included in a signature).
To confirm that a public key really belongs to a subject, a certificate authority is used that ensures this fact with a signature.
A certificate is a public key signed by a certificate authority. Since a private key should be protected, it exists in a container. Key container can include an open key in addition to a private key (e.g., as a certificate).
Cryptographic extension should be installed for the web client to work. The web client specifies that the user permission query is executed for some operations (file system access and private key access).
22.2. MAIN CONCEPTS
Some terms will be used to describe the mechanisms covered in this section.
Digital signature – a series of data generated as a result of cryptographic transformation of source information using a digital signature private key. It can be used to confirm integrity and invariability of this information and its authenticity, if a digital signature public key and its certificate are used.
Digital signature authenticity confirmation center (hereinafter referred to as Certification authority) – a legal entity or a dedicated legal entity department with privileges to confirm the authenticity of the digital signature public key owner.
Key certificate owner – a person for which a public key certificate is generated by a certification authority and who owns a corresponding private (secret) key.
Certificate – a digital document including a public key and information about the key owner certified by a certification authority using a digital signature.
Cryptographic module – a library of functions that directly implements cryptographic algorithms or provides access to encryption mechanisms.
22.3. GENERAL PRINCIPLES OF USING CRYPTOGRAPHIC MECHANISMS
Two main usage options can be identified when cryptographic mechanisms are used:
data encryption/decryption
data signing/signature validation
General encryption/decryption principles can be described as follows:
A necessary object for access to cryptographic functionality is created (the CryptoManager object).
A necessary certificate is selected that is a public key of the receiver side (the CryptoCertificate object). This certificate is used to encrypt data.
Required files or binary data are encrypted using the Encrypt() methods of the CryptoManager object created.
Encrypted data are ready for transfer via public channels.
When encrypted data are received, reverse operation is executed.
A necessary object for access to cryptographic functionality is created that should match the object used for data encryption.
Received data are decrypted using the Decrypt() method of the created cryptographic functionality object.
General signing/signature validation principles can be described as follows:
A necessary object for access to cryptographic functionality is created (the CryptoManager object).
A necessary certificate is selected that is a private key of the signing side (the CryptoCertificate object). This key is used to generate a digital signature.
A digital signature for the required file or binary data is generated using the Sign() method of the CryptoManager object created.
Signed data with the digital signature are sent to the receiver side.
When signed data and the digital signature are received, reverse operation is executed.
A necessary object for access to cryptographic functionality is created that should match the object used to generate a digital signature.
The digital signature is validated using the VerifySignature() method of the cryptographic functionality object created.
Certificates necessary for cryptographic operations are received from a corresponding certification authority.
It is not recommended to get several certificate storages with similar characteristics when you are working with the CryptoManager object, since changing one storage will lead to a different behavior of the other storage depending on the cryptographic modules being used.
22.4. WORKING WITH CRYPTOGRAPHIC MODULES
Microsoft CryptoAPI is used to interact with cryptographic modules in Windows.
Direct interaction with the installed components is used to interact with cryptographic modules in Linux.
The following components are supported:
CryptoPro cryptographic information protection tool. To use this tool, specify 75 as the CryptographicModuleType parameter of the CryptoManager object.
22.5. USAGE EXAMPLES
This section provides examples of some typical tasks executed using cryptographic mechanisms.
Creating an object to access cryptographic functionality
Creating an object to access cryptographic functionality is a basic operation, without which further operations with the cryptographic mechanism are not available.
CryptoManager = New CryptoManager("", "", 75);
This example creates a module to work with Russian cryptographic modules (the CryptographicModuleType parameter value is 75).
Getting a list of certificates
A list of certificates from selected certificate storages is generated that will be used in further operations.
&AtClient
Function GetCertificateList(CryptographyManagerType, TypesArray, CheckExpirationDate)
// List of certificates
CertificateList = New Array;
CryptoManager = New CryptoManager("", "", CryptographyManagerType);
For Each StorageType In TypesArray Do
// Get certificates for each type of certificates storage
Storage = CryptoManager.GetCertificateStore(StorageType);
// Select all certificates
StorageCertificates = Storage.GetAll();
CurrentDate = CurrentDate();
For Each Certificate In StorageCertificates Do
If CheckExpirationDate And Certificate.EndDate < CurrentDate Then
// Skip expired certificates, if needed
Continue;
EndIf;
CertificateList.Add(Certificate);
EndDo;
EndDo;
Return CertificateList;
EndFunction
&AtClient
Procedure ObtainCertificateList()
StorageTypes = New Array;
StorageTypes.Add(CryptoCertificateStoreType.PersonalCertificates);
StorageTypes.Add(CryptoCertificateStoreType.RecipientCertificates);
List = GetCertificateList(75, StorageTypes, True);
// ...
EndProcedureFile encryption
A file selected interactively is encrypted and then written to a disk of a client computer.
For demonstration, encryption operation always uses the first certificate in the list of all of certificates installed on the computer.
&AtServer
Function EncryptAtServer(DataAddress, CertificatesData)
// Create certificates on the basis of binary data certificates // from the client
Certificates = New Array();
For Each CertificateData In CertificatesData Do
Certificates.Add(New CryptoCertificate(CertificateData));
EndDo;
CryptoManager = New CryptoManager("", "", 75);
// Get file for encryption from the temporary storage
Data = GetFromTempStorage(DataAddress);
If TypeOf(Data) <> Type("BinaryData") Then
Return False;
EndIf;
// Encrypt binary data
EncryptedBinaryData = CryptoManager.Encrypt(Data, Certificates);
// Save to temporary storage
DataAddress = PutToTempStorage(EncryptedBinaryData);
Return True;
EndFunction
&AtClient
Procedure FileEncryption()
Address = "";
Result = PutFile(Address, , , True);
If Not Result Then
Return;
EndIf;
CertificateTypes = New Array;
CertificateTypes.Add(CryptoCertificateStoreType.PersonalCertificates);
List = GetCertificateList(75, CertificateTypes, True);
// In this example we always encrypt using the first by order certificate
Certificates = New Array;
Certificates.Add(List[0].Unload());
// Encrypt file
Result = EncryptAtServer(Address, Certificates);
If Not Result Then
Return;
EndIf;
// Interactively save encrypted file to disk
GetFile(Address, , True);
EndProcedureFile decryption
An attempt to decrypt the selected file is executed. It is necessary to implement the GetAccessPassword() function that returns the password to access the private key.
NOTE
When the Decrypt() method is used, an exception is called only when decryption attempts using all available certificates have failed, not just after the first error.
&AtClient
Procedure FileDecryption()
// Choose encrypted file
Address = "";
Result = PutFile(Address, , , True);
If Not Result Then
Return;
EndIf;
Data = GetFromTempStorage(Address);
// Decrypt file
CryptoManager = New CryptoManager("", "", 75);
CryptoManager.PrivateKeyAccessPassword = GetAccessPassword();
DecryptedData = CryptoManager.Decrypt(Data);
Address = PutToTempStorage(DecryptedData);
GetFile(Address, , True);
EndProcedureDigital signature generation
A file with a digital signature is generated. In this example the digital signature is always saved in the signature.sign file. It is necessary to implement the GetAccessPassword() function that returns the password to access the private key.
&AtClient
Procedure SignFile()
Address = "";
Result = PutFile(Address, , , True);
If Not Result Then
Return;
EndIf;
CertificateTypes = New Array;
CertificateTypes.Add(CryptoCertificateStoreType.PersonalCertificates);
List = GetCertificateList(75, CertificateTypes, True);
Certificate = List[0];
Data = GetFromTempStorage(Address);
CryptoManager = New CryptoManager("", "", 75);
CryptoManager.PrivateKeyAccessPassword = GetAccessPassword();
CryptoManager.Sign(Data, "signature.sign", Certificate);
EndProcedureDigital signature validation
This function validates digital signature authenticity for the original file – digital signature file combination.
&AtClient
Function CheckFileSignature(SignedFileName, SignatureFileName)
Certificate = Undefined;
CryptoManager = New CryptoManager("", "", 75);
Try
CryptoManager.VerifySignature(SignedFileName, SignatureFileName, Certificate);
Except
Return False;
EndTry
Return True;
EndFunction