N/certificateControl Module – JCurve Solutions

Note: The content in this help topic pertains to SuiteScript 2.0 and SuiteScript 2.1.

The N/certificateControl module enables scripting access to the Digital Certificates list found in the UI at Setup > Company > Certificates. You can use this module to find, create, update, read and delete certificates records. For more information, see Digital Signing and Uploading Digital Certificates.

To access this module, you must use the Execute As Role field on the script deployment record. Select either the Administrator role or a custom role with the Certificate Access permission. For more information, see Access to Digital Certificates.

Important

The certificate record holds information for a digital certificate, but it is not a standard NetSuite record and cannot be accessed with the N/record.

N/certificateControl Module Members

Member Type

Name

Return Type / Value Type

Supported Script Types

Description

Object

certificateControl.Certificate

object

Server scripts

Encapsulates a digital certificate record.

Method

certificateControl.findCertificates(options)

object

Server scripts

Returns metadata about the certificate(s).

certificateControl.findUsages(options)

object[]

Server scripts

Returns an audit trail of how a certificate has been used. Includes operations performed with time stamps.

certificateControl.createCertificate(options)

certificateControl.Certificate

Server scripts

Creates a certificate record using a file from the File Cabinet. After saving with Certificate.save(), the certificate is accessible on the Certificates.

certificateControl.deleteCertificate(options)

string

Server scripts

Deletes a certificate record that has been uploaded to the Certificates list in the UI or created using certificateControl.createCertificate(options) and saved with Certificate.save().

certificateControl.loadCertificate(options)

certificateControl.Certificate

Server scripts

Loads a certificate record that has been uploaded to the Certificates list in the UI or created using certificateControl.createCertificate(options).

certificateControl.lock(options)

string

Server scripts

Locks a certificate record so that it cannot be edited.

certificateControl.unlock(options)

string

Server scripts

Unlocks a certificate record that has been locked with certificateControl.lock(options).

Enum

certificateControl.Operation

enum

Server scripts

Holds the values for the operation when searchng for certificates with certificateControl.findUsages(options).

certificateControl.Operator

enum

Server scripts

Holds string values for search operators to use with the name and description parameters of the certificateControl.findCertificates(options).

certificateControl.Type

enum

Server scripts

Certificate Object Members

The following members are called on the certificateControl.Certificate object.

Member Type

Name

Return Type / Value Type

Supported Script Types

Description

Method

Certificate.save()

object containing the script ID of the new certificate record

Server scripts

Saves a certificate record.

Property

Certificate.description

string

Server scripts

Describes the certificate record.

Certificate.file

File Object Members object

Server scripts

Includes the properties of the file uploaded to create the certificate.

Certificate.name

string

Server scripts

The name of the certificate record.

Certificate.monthReminder

boolean

Server scripts

Indicates the setting of the Month box for Expiration Reminders on the certificate record.

Certificate.notifications

number[]

Server scripts

The internal IDs of the employees selected in the Copy Employees field on the certificate record.

Certificate.password

string (write-only)

Server scripts

The password for the digital certificate. You can create a GUID for the password using Form.addSecretKeyField(options) or you can create an API secret for the secret at Setup > Company > API Secrets.

Certificate.restrictions

number[]

Server scripts

The internal IDs of the employees selected in the Restrict to Employees field of the certificate record.

Certificate.scriptId

string

Server scripts

The ID of the certificate record.

Certificate.subsidiaries

number[]

Server scripts

The internal IDs of the subsidiaries associated with the certificate record.

Certificate.threeMonthsReminder

boolean

Server scripts

Indicates the setting of the 3 Months box for Expiration Reminders on the certificate record.

Certificate.weekReminder

boolean

Server scripts

Indicates the setting of the Week box for Expiration Reminders on the certificate record.

N/certificateControl Module Script Samples

Filter the Digital Certificates list by subsidiary and file type

Note

This sample script uses the require function so that you can copy it into the SuiteScript Debugger and test it. You must use the define function in an entry point script (the script you attach to a script record and depoly). For more information, see SuiteScript 2.x Script Basics and SuiteScript 2.x Script Types.

The following sample shows how to filter the Digital Certificates list by subsidiary and by file type.

/**
 * @NApiVersion 2.x
   */
require(['N/certificateControl'],
      function(certificateControl){
         var all = certificateControl.findCertificates();
         var specificType = certificateControl.findCertificates({
              type: 'PFX'
         });
         var specificSub = certificateControl.findCertificates({
              subsidiary: 93
         });
         var specificTypeAndSub = certificateControl.findCertificates({
               type: 'PFX',
               subsidiary: 93
         });

Find the audit trail of POST operations for the certificate record with ID

Note

This sample script uses the require function so that you can copy it into the SuiteScript Debugger and test it. You must use the define function in an entry point script (the script you attach to a script record and deploy). For more information, see SuiteScript 2.x Script Basics and SuiteScript 2.x Script Types.

The following sample shows how to find the audit trail of POST operations for the certificate record with ID ‘custcertificate_china’.

/**
 * @NApiVersion 2.x
   */

require(['N/certificateControl'], function(cc){
    var usages = cc.findUsages({
        id: 'custcertificate_china',
            operation: cc.Operation.POST
       });
})

Create a File object by loading a file from the File Cabinet

Note

This sample script uses the require function so that you can copy it into the SuiteScript Debugger and test it. You must use the define function in an entry point script (the script you attach to a script record and deploy). For more information, see SuiteScript 2.x Script Basics and SuiteScript 2.x Script Types.

The following sample shows how to create a file object by loading a file from the File Cabinet. It then creates the options needed for the certificateControl.createCertificate(options) method and creates and saves the certificate record. The certificate record is then loaded again, edited to the change the file, and saved again.

/**
 * @NApiVersion 2.x
   */

require(['N/certificateControl','N/file'],function(cc, file){
    var fileObj = file.load({
        id: 'SuiteScripts/dsa.p12'
    });
    var options = {
        file : fileObj,
        password : '022b490ad4334c7e86a8304f937ec68f',
        name : 'testCert',
        description : 'testDescription',
        scriptId : '_testid',
        subsidiaries : [1,3],
        weekReminder : false,
        monthReminder : true,
        threeMonthsReminder : false
    };
    var newCertificate = cc.createCertificate(options);
    newCertificate.save();

    var loadedCertificate = cc.loadCertificate({
           scriptId : 'custcertificate_testid'
    });
    fileObj = file.load({
        id: 'SuiteScripts/ecdsa.p12'
    });
    loadedCertificate.file = fileObj;
    loadedCertificate.password = '022b490ad4334c7e86a8304f937ec68f';
    loadedCertificate.save();
})

Find an existing certificate record

Note

This sample script uses the require function so that you can copy it into the SuiteScript Debugger and test it. You must use the define function in an entry point script (the script you attach to a script record and deploy). For more information, see SuiteScript 2.x Script Basics and SuiteScript 2.x Script Types.

The following sample shows how to find an existing certificate record and use it in an operation.

/**
 * @NApiVersion 2.x
   */

require(['N/certificateControl','N/https/clientCertificate'],function(cc, cert){
    var yodlee = cc.findCertificates({
        name: 'Yodlee',
        description: 'Yodlee certificate'
    });
    cert.post({certId:yodlee[0].id,url:<url>, body:<body>, headers:<headers>
    });
})

Generate signature of a plaintext string and verify the signature using the same certificate

Note

This sample script uses the require function so that you can copy it into the SuiteScript Debugger and test it. You must use the define function in an entry point script (the script you attach to a script record and deploy). For more information, see SuiteScript 2.x Script Basics and SuiteScript 2.x Script Types.

The following sample shows how to generate a signature of a plaintext string and then verifies the signature using the same certificate.

/**
 * @NApiVersion 2.x
 */

require({'N/certificateControl','N/crypto/certificate'], function(cc, certificate){
    var signer = certificate.createSigner({
        certId:'custcertficiate_cert_1',
        algorithm: 'SHA256'
        });
    var result = signer.sign();
    var verifier = certificate.createVerifier({
        certId: 'custcertificate_cert_1',
        algorithm: 'SHA256'
        });
    verifier.update('test');
    verifier.verify(result);
    var res = cc.findUsages();
    ;
})

The res variable returns an array of information about the usage of the digital certificate, including the date of the action, the type of operation, such as sign, and the internal ID of the person who performed the action.

Establish SFTP connection using an SSH key

Note

This sample script uses the require function so that you can copy it into the SuiteScript Debugger and test it. You must use the define function in an entry point script (the script you attach to a script record and deploy). For more information, see SuiteScript 2.x Script Basics and SuiteScript 2.x Script Types.

The following sample establishes a SFTP connection using an SSH key that has already been uploaded to NetSuite. It then creates, updates, loads, and deletes a certificate record to show the full CRUD operation. Replace the server URL with your correct URL.

For the SFTP connection, the public key corresponding to the private key in the certificate must be stored in the .ssh/authorized_keys file on the server.

/**
 * @NApiVersion 2.x
 */

require(['N/file', 'N/sftp', 'N/certificateControl'], function(file, sftp, certificateControl) {
    var certPath = 'yyy/certificates'
    var certName = 'apiclient_cert.p12';

// Establish SFTP connection
    log.debug('Establishing secured SFTP connection...');
    var connection = sftp.createConnection({
        username: 'sftpuser',
        keyId: 'custkeysftp_nft_demo_key',
        url: 'my.sftp.example.com',
        port: 22,
        directory: 'inbound',
        hostKey: 'AAAAB3NzaC1yc2EAAAADAQABAAABAQC4gYD1K4lE9QnuYEgRRQChjrAM1+bTT95e71Xv0oQ60ywVQEiedhRqSMbPiCPPB4pjpBdOmPIQCCkug+3XwAQ6uNj3UM11zoGGmg86tyEJT6qGB0SsrQJzHTb3EG38BSrBO0WEzOWeJ8E8YODT3oAj1Nrf8Ls3JbGObRF+0uwJDIllSrFkYS3kWCV27NhBnaytGe7iLBgrJdNVlitNqkxZfK0NsAYCaJWQjQLtz+GFfN5zTbKKNsDa6s/YW7oAMMOI3Q5GQAqdXtKY728WvxYTjr2FsYS/KM6nbq/csTvZHWLE0z2TQtB2H0IIofvEP/QvXwmgEnCeVPcNgRwdHWQf'
        });
    log.debug('Connection established!');
// ------------------------------------------------------------------------

// Create new certificate
    log.debug('Creating certificate...');
    var certScriptId = '_' + (Math.random().toString(36).substring(2, 10));
    var cert = certificateControl.createCertificate();
    cert.name = 'Test Certificate China API';
      cert.description = 'Test Certificate China created using API';
// custcertificate prefix will be added automatically
      cert.scriptId = certScriptId;
      log.debug('Downloading certificate file from SFTP...');
      cert.file = connection.download({
        directory: certPath,
        filename: certName
        });
    log.debug('Successfully downloaded!');
    //guid corresponding to the certificate's password';
    var pwd = '022b490ad4334c7e86a8304f937ec68f',
    cert.password = pwd;
    cert.save();
/**/certScriptId = 'custcertificate' + certScriptId;
log.debug('Certificate "' + cert.name + '" successfuly created with id "' + certScriptId + '"!');
// ------------------------------------------------------------------------
// Rename certificate
      log.debug('Renaming certificate...');
   cert = certificateControl.loadCertificate({scriptId: certScriptId});
      cert.name = 'Test Certificate China API TEMP';
      cert.save();
// Verify new certificate name
/**/cert = certificateControl.loadCertificate({scriptId: certScriptId});
      log.debug('Certificate successfully renamed to "' + cert.name + '"');
// ------------------------------------------------------------------------
// Delete certificate
      log.debug('Deleting certificate "' + cert.name + '"...');
      certificateControl.deleteCertificate(certScriptId);
      log.debug('Certificate deleted!');
// ------------------------------------------------------------------------
// Load the deleted certificate
      log.debug('Attempting to load the deleted certificate to invoke an error...');
      try {
           cert = certificateControl.loadCertificate({scriptId: certScriptId});
          }
    catch (e) {
           log.error(e.message);
          }
})

N/certificateControl Module Members

Certificate Object Members

N/certificateControl Module Script Samples

Filter the Digital Certificates list by subsidiary and file type

Find the audit trail of POST operations for the certificate record with ID

Create a File object by loading a file from the File Cabinet

Find an existing certificate record

Generate signature of a plaintext string and verify the signature using the same certificate

Establish SFTP connection using an SSH key

Related articles